# Start

> Smart session onboarding — checks for handoff artifacts first, then checkpoints, then offers fresh start with sprint contract. No assumptions about session state.

- Skill: `fanlw0816/start` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fanlw0816/start`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fanlw0816/start/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fanlw0816 (https://skillmd.com/u/fanlw0816)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fanlw0816/start

---


# Start Skill

You are facilitating smart session onboarding. Your role is to detect any saved progress and offer continuation, or guide a fresh start with proper context setup.

## Purpose

The `/start` skill ensures:
- No lost work between sessions
- Smooth context reset transitions
- Clear session state from the beginning
- Proper sprint contract for fresh starts

## Onboarding Flow

```
Session Start
    |
    +--[1] Handoff artifact exists? (.claude/handoff.md)
    |       |
    |       +-- YES --> Load handoff, continue work
    |       |           Show: Session summary, current state, next step
    |       |           Ask: "Continue from handoff?"
    |       |
    |       +-- NO --> Continue to [2]
    |
    +--[2] Checkpoint exists? (.claude/checkpoint.md)
    |       |
    |       +-- YES --> Load checkpoint, offer resume
    |       |           Show: Last saved state, time since save
    |       |           Ask: "Resume from checkpoint?"
    |       |
    |       +-- NO --> Continue to [3]
    |
    +--[3] Fresh Start
            |
            +-- Check for project context (CLAUDE.md, .claude/)
            +-- Offer: Load project or start sprint contract
            +-- Guide: Set up session with clear goals
```

## Detection Logic

### 1. Handoff Artifact Check

**Location**: `.claude/handoff.md`

Handoff artifacts are created during context reset. They contain:
- Session summary
- Completed work
- Current state
- Next immediate step
- Key decisions
- Open questions
- Resume commands

**If found**:
```
HANDOFF DETECTED: Previous session requested context reset.

Session Summary: [From handoff artifact]
Current State: [From handoff artifact]
Next Step: [From handoff artifact]

Options:
1. Continue from handoff (recommended for context reset)
2. Ignore and check for checkpoint
3. Fresh start (discards handoff context)

What would you like to do?
```

### 2. Checkpoint Check

**Location**: `.claude/checkpoint.md`

Checkpoints are manual saves during sessions. They contain:
- Timestamp
- Work in progress
- Files being modified
- Current task
- Blockers/notes

**If found**:
```
CHECKPOINT DETECTED: Previous session saved progress.

Saved: [timestamp from checkpoint]
Task: [current task from checkpoint]
Files: [modified files list]

Options:
1. Resume from checkpoint
2. Ignore and start fresh
3. View checkpoint details first

What would you like to do?
```

### 3. Fresh Start

**No saved progress found**:
```
FRESH SESSION

Project: [detected from CLAUDE.md or git]
Branch: [current git branch]
Recent commits: [last 3 commits]

Options:
1. Start new feature (sprint contract flow)
2. Load existing project context
3. Continue recent work [show last commit]
4. Custom task

What would you like to work on?
```

## Sprint Contract Flow (Fresh Start)

When starting fresh with new work:

### Step 1: Define Scope
```
What are you building?
- Feature name/description
- Target components (frontend/backend/database)
- Success criteria (what does "done" look like?)
```

### Step 2: Generate Contract
Create a sprint contract with:
- Clear scope boundaries
- Testable behaviors
- Acceptance criteria

### Step 3: Confirm Contract
```
SPRINT CONTRACT GENERATED

Scope: [summary]
Behaviors: [count] testable criteria
Acceptance: [count] pass/fail conditions

1. Accept and begin implementation
2. Modify contract
3. Save for later

Proceed with implementation?
```

## Session State Tracking

After onboarding, maintain session state:

```markdown
# Active Session: [session-id]

## Context Source
- [ ] Handoff (context reset)
- [ ] Checkpoint (manual save)
- [ ] Fresh start (new session)

## Current Work
- Task: [active task]
- Status: [status]
- Started: [timestamp]

## Sprint Contract
- File: .claude/sprint-contract.md
- Status: [DRAFT/ACTIVE/COMPLETE]

## Files in Progress
- [file1]: [status]
- [file2]: [status]

## Notes
- [session notes]
```

## Implementation Checklist

When running `/start`, execute in order:

1. [ ] Check for `.claude/handoff.md`
2. [ ] Check for `.claude/checkpoint.md`
3. [ ] Check for `.claude/session-state.md`
4. [ ] Detect project context (CLAUDE.md, package.json, etc.)
5. [ ] Present appropriate options
6. [ ] Load selected context
7. [ ] Initialize session state file
8. [ ] Confirm ready state with user

## Output Format

```
SESSION READY

Context: [handoff/checkpoint/fresh]
Task: [active task or "awaiting input"]
Contract: [active/draft/none]
Progress: [if resuming, show % complete]

Next action: [suggested first action]

Ready to proceed!
```

## Usage

```
/start                    # Auto-detect saved progress
/start --fresh            # Skip all saved progress
/start --checkpoint       # Force checkpoint resume
/start --handoff          # Force handoff resume
```

## Integration Points

- **With /checkpoint**: Creates checkpoints for future sessions
- **With /resume**: Loads specific checkpoint by ID
- **With sprint-contract**: Initiates contract flow for fresh starts
- **With hooks**: session-start.sh calls this skill automatically