---
description: "Session bootstrap - read project context, restore saved state, show status. Quick orientation with optional deep dive."
---

# Sync - Session Bootstrap & Restore

Read yourself into this project and restore any saved session state. Fast, direct file reads.

**Environment Requirements:**
- All shell commands use **Git Bash syntax** (works on Linux/macOS/Windows)
- NEVER use Windows cmd syntax (`find /c`, `2>nul`) - causes filesystem scanning on Git Bash
- Use `wc -l` for counting, `2>/dev/null` for error suppression

## Arguments

$ARGUMENTS

- No args: Quick bootstrap + restore saved state + show status
- `--verbose`: Deep bootstrap - also reads all `*.md` in root + `docs/`
- `--diff`: Show what changed since last save
- `--git`: Auto-update plan steps from recent commits
- `--status`: Just show status (skip restore prompt)

## Architecture

```
/sync [--verbose|--diff|--git|--status]
    |
    +--> Default (no args): FULL BOOTSTRAP
    |      |
    |      +- Read project context (README, AGENTS, CLAUDE)
    |      +- Read saved state (.claude/session-cache.json)
    |      +- Restore tasks via TaskCreate
    |      +- Read plan (docs/PLAN.md)
    |      +- Show unified status
    |      +- Suggest next action
    |
    +--> --verbose: DEEP BOOTSTRAP
    |      |
    |      +- Everything above, plus:
    |      +- Read all *.md in project root
    |      +- Read all *.md in docs/
    |
    +--> --diff: CHANGE DETECTION
    |      |
    |      +- Compare current state vs saved state
    |      +- Show new commits since save
    |      +- Show file changes since save
    |
    +--> --git: AUTO-UPDATE FROM COMMITS
    |      |
    |      +- Parse recent git commits
    |      +- Match to plan steps
    |      +- Update step status
    |
    +--> --status: STATUS ONLY
           |
           +- Show current status
           +- Skip restore prompt
           +- Read-only quick view
```

---

## Default Mode: `/sync`

Full bootstrap with state restoration.

### Step 1: Parallel Reads

Read these files simultaneously (skip any that don't exist):

| File | Purpose |
|------|---------|
| `README.md` | Project overview |
| `AGENTS.md` | Agent instructions |
| `CLAUDE.md` | Project-specific rules |
| `docs/PLAN.md` | Current plan |
| `.claude/session-cache.json` | Saved session state |

### Step 2: Restore Session State

If `.claude/session-cache.json` exists:

```
1. Parse saved tasks array from JSON
2. For each task, call TaskCreate with:
   - subject
   - description
   - activeForm
3. Build ID mapping: savedIndex → newTaskId
4. For each task with blockedBy, call TaskUpdate:
   - Map saved indices to new task IDs
   - Set blockedBy relationships
5. For each task, call TaskUpdate to set status:
   - "completed" | "in_progress" | "pending"
6. Note time since last save
```

Note: Tasks do not persist across sessions automatically, which is why this restore step is needed.

### Step 3: Parallel Globs

Discover extensions:

```
docs/*.md
commands/*.md OR .claude/commands/*.md
skills/*/SKILL.md OR .claude/skills/*/SKILL.md
agents/*.md OR .claude/agents/*.md
```

### Step 4: Git State

**CRITICAL:** Use Git Bash syntax ONLY. Never use Windows cmd syntax (`find /c`, `2>nul`) - these will cause filesystem scanning.

Run these commands to get git state:

```bash
# Current branch
git branch --show-current 2>/dev/null

# Count uncommitted files - MUST use wc -l (works in Git Bash on Windows)
git status --porcelain 2>/dev/null | wc -l

# Latest commit
git log -1 --format="%h %s" 2>/dev/null
```

**Why this matters on Windows:**
- `find /c` in Git Bash = Unix find searching C: drive (WRONG)
- `wc -l` in Git Bash = count lines (CORRECT)
- Git Bash understands `2>/dev/null` but NOT `2>nul`

### Step 5: Output

Format and display unified status.

---

## Output Format

### With Saved State

```
Project Synced: [project-name]

## Session Restored

| Field | Value |
|-------|-------|
| **Last saved** | 2 hours ago |
| **Branch** | feature/auth |
| **Notes** | "Stopped at callback URL issue" |

## Plan Status

**Goal**: Add user authentication with OAuth2

| Step | Status |
|------|--------|
| Step 1: Research OAuth providers | Done |
| Step 2: Set up Google OAuth app | Done |
| Step 3: Implement OAuth flow | **Current** |
| Step 4: Add token refresh | Pending |
| Step 5: Write integration tests | Pending |

Progress: 40% (2/5)

## Restored Tasks

| Status | Task |
|--------|------|
| Done | Set up OAuth credentials |
| **In Progress** | Fix callback URL handling |
| Pending | Add token refresh logic |

## Git

| Field | Value |
|-------|-------|
| **Branch** | feature/auth |
| **Uncommitted** | 3 files |
| **Last commit** | abc123f feat: Add OAuth config |

## Quick Reference

| Category | Items |
|----------|-------|
| **Commands** | /save, /sync, /review, /testgen... |
| **Skills** | 30 available |
| **Agents** | 23 available |

## Next Steps

1. **Continue**: Fix callback URL handling
2. **Check diff**: /sync --diff to see changes since save
```

### Without Saved State

```
Project Synced: [project-name]

## Summary

[1-2 paragraph narrative based on README.md and AGENTS.md]

## Quick Reference

| Category | Items |
|----------|-------|
| **Project** | [name] - [purpose] |
| **Key Docs** | [list of docs/*.md] |
| **Commands** | [list of /commands] |
| **Skills** | [count] available |
| **Agents** | [count] available |
| **Plan** | No active plan |
| **Saved State** | None |
| **Git** | [branch], [N] uncommitted |

## Next Steps

1. **Ready for new task** - No pending work detected
2. **Create a plan** - Use native /plan for implementation planning
3. **Save before leaving** - /save "notes" to persist state
```

---

## Verbose Mode: `/sync --verbose`

Deep context loading for onboarding or complex tasks.

### Additional Reads

| Location | Files Read |
|----------|------------|
| Project root | All `*.md` files |
| `docs/` | All `*.md` files |

### Output

Same as default, plus:

```
## Documentation Loaded

| File | Summary |
|------|---------|
| CONTRIBUTING.md | Contribution guidelines |
| CHANGELOG.md | Recent changes |
| docs/ARCHITECTURE.md | System architecture |
| docs/WORKFLOWS.md | Development workflows |
| ... | ... |
```

---

## Diff Mode: `/sync --diff`

Show what changed since last save.

### Output

```
Changes Since Last Save

## Time

| Field | Value |
|-------|-------|
| **Saved** | 2025-12-13 10:30 AM |
| **Now** | 2025-12-13 12:45 PM |
| **Elapsed** | 2 hours 15 minutes |

## Git Changes

| Type | Count |
|------|-------|
| **New commits** | 3 |
| **Files changed** | 7 |
| **Insertions** | +142 |
| **Deletions** | -38 |

### Recent Commits

| Hash | Message |
|------|---------|
| def456 | fix: Handle redirect edge case |
| abc123 | feat: Add callback validation |
| 789xyz | test: Add OAuth flow tests |

## Plan Changes

| Field | Saved | Current |
|-------|-------|---------|
| **Current step** | Step 3 | Step 3 |
| **Progress** | 40% | 40% |
| **Status** | No change | - |

## Task Changes

| Change | Task |
|--------|------|
| **Completed** | Fix callback URL handling |
| **New** | Add error handling for token refresh |
```

---

## Git Sync Mode: `/sync --git`

Auto-update plan steps from recent commits.

### How It Works

1. Parse recent git commits (last 20)
2. Match commit messages to plan steps using keywords
3. Update step status in `docs/PLAN.md`

### Matching Rules

| Commit Pattern | Plan Update |
|----------------|-------------|
| `feat: Add OAuth...` | Mark matching step complete |
| `fix: Token refresh...` | Mark matching step in-progress |
| `test: OAuth flow...` | Mark matching test step complete |

### Output

```
Git Sync

## Matches Found

| Commit | Plan Step | Action |
|--------|-----------|--------|
| abc123 "feat: Add OAuth config" | Step 2 | Marked complete |
| def456 "fix: Callback handling" | Step 3 | Marked in-progress |

## Updated docs/PLAN.md

| Step | Previous | New |
|------|----------|-----|
| Step 2 | In Progress | Done |
| Step 3 | Pending | In Progress |
```

---

## Status Mode: `/sync --status`

Quick read-only status view. No restore prompt.

### Output

```
Status

## Plan

**Goal**: Add user authentication with OAuth2
**Progress**: 40% (2/5)
**Current**: Step 3 - Implement OAuth flow

## Tasks

| Status | Count |
|--------|-------|
| Completed | 1 |
| In Progress | 1 |
| Pending | 1 |

## Git

| Field | Value |
|-------|-------|
| **Branch** | feature/auth |
| **Uncommitted** | 3 files |
```

---

## Edge Cases

### No README.md
```
Warning: No README.md found - project overview unavailable
```

### No docs/ directory
```
Info: No docs/ directory - documentation not set up
```

### First time in project
```
Info: Fresh project - no Claude configuration found
Consider: Create CLAUDE.md for project-specific rules
```

### Stale saved state (>7 days)
```
Warning: Saved state is 12 days old

Options:
  1. Restore anyway (tasks may still be relevant)
  2. Start fresh: /save --archive
```

### Legacy v2.0 schema (todos object)
```
Info: Found v2.0 session-cache.json (legacy format)

Converting todos to tasks:
  - 3 completed → tasks with status: "completed"
  - 1 in_progress → tasks with status: "in_progress"
  - 2 pending → tasks with status: "pending"

Note: Legacy format lacks descriptions and dependencies.
Consider running /save to upgrade to v3.0 schema.
```

**Migration logic:**
```
if version == "2.0" and "todos" in json:
    for task in todos.completed:
        TaskCreate(subject=task, description="(migrated from v2.0)", status="completed")
    for task in todos.in_progress:
        TaskCreate(subject=task, description="(migrated from v2.0)", status="in_progress")
    for task in todos.pending:
        TaskCreate(subject=task, description="(migrated from v2.0)", status="pending")
```

### Branch changed since save
```
Warning: Branch changed since save

| Field | Value |
|-------|-------|
| **Saved on** | feature/old-branch |
| **Current** | feature/new-branch |

Restore anyway? Tasks may not apply to current branch.
```

---

## Integration

| Command | Relationship |
|---------|--------------|
| `/sync` | **This command** - Read state in |
| `/save` | Complementary - Persist state out |
| Native `/plan` | Claude Code's planning mode |

### Typical Session Flow

```
Session Start
  /sync                    <- Read project, restore state

During Work
  /sync --status           <- Quick status check
  /sync --diff             <- What changed?
  /sync --git              <- Update from commits

Session End
  /save "notes"            <- Persist before leaving
```

---

## Flags Reference

| Flag | Effect |
|------|--------|
| (none) | Full bootstrap + restore + status |
| `--verbose` | Also read all *.md in root + docs/ |
| `--diff` | Show changes since last save |
| `--git` | Auto-update plan from commits |
| `--status` | Status only, skip restore prompt |

---

## Notes

- **Read-focused** - Only `/save` writes files
- **Fast by default** - Parallel reads, minimal overhead
- **Git-aware** - Tracks branch, commits, uncommitted changes
- **Smart restore** - Detects stale state, branch changes
- Works in any project, with or without Claude configuration