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: d3fc69a973
Branches Tags
claude-mods
/
commands
/
sync.md

sync.md 12 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
    |      +- Resolve plan path (Step 0)
    |      +- Read plan (<plan-path>)
    |      +- Acknowledge memory context (already auto-loaded)
    |      +- 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 0: Resolve Plan Path

Determine the plan file location before reading:

  1. If saved state exists (.claude/session-cache.json) and has a plan.file value, prefer that path
  2. Else check .claude/settings.local.json for a plansDirectory key
  3. Else check .claude/settings.json for plansDirectory
  4. If found, plan path = <plansDirectory>/PLAN.md
  5. Otherwise, default to docs/PLAN.md

Use the resolved path in all subsequent file reads and output.

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
<plan-path> Current plan (resolved in Step 0)
.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
7. If session_id present, note it for --resume suggestion in output
8. If git.pr_number/pr_url present, note for --from-pr suggestion in output

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: Acknowledge Memory

MEMORY.md is auto-loaded into the system prompt by Claude Code - do NOT re-read the file. Instead, check your system prompt for the memory content you already have, and surface it:

  • If MEMORY.md has content (non-empty), summarise what it contains (especially any ## Last Session section written by /save)
  • If MEMORY.md is empty, note "Memory: Empty (no notes from previous sessions)"

This costs zero extra tokens while confirming the safety net is working.

Step 6: 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 |
| **Previous session** | abc123... |
| **Notes** | "Stopped at callback URL issue" |

Note: Previous session row only shown when session_id is present in saved state.

## 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 |
| **PR** | #42 - https://github.com/user/repo/pull/42 |

Note: PR row only shown when pr_number/pr_url are present in saved state.

## Memory

[If MEMORY.md has content, summarise key points - especially any `## Last Session` section]
[If MEMORY.md is empty: "No memory notes from previous sessions."]

Note: MEMORY.md is auto-loaded into the system prompt. This section surfaces
what's already in context - no file read needed.

## 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
3. **Resume conversation**: `claude --resume abc123...` (when session_id present)
4. **PR context**: `claude --from-pr 42` (when PR is linked)

Note: Next Steps items 3-4 are only shown when the corresponding data exists in saved state.

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 |
| **Memory** | [summary of MEMORY.md content, or "Empty"] |
| **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 the resolved plan path

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

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

## Memory

[Summary of MEMORY.md content, or "Empty"]

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

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