Home Explore Help
Sign In
logic855
/
claude-mods
mirror of https://github.com/0xDarkMatter/claude-mods.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: 9a80eb5c10
Branches Tags
claude-mods
/
commands
/
sync.md

sync.md 11 KB
History Raw

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:

# 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