superspec sync

Sync git changes to context.md for Vibe Coding context restoration.

Syntax

superspec sync [name] [options]

Arguments

Argument	Description	Required
[name]	Change name	No (syncs all by default)

Options

Option	Description	Default
--base <branch>	Base branch	main or master
--no-git	Don't collect git diff	false

Features

The sync command will:

1. Collect git diff of current branch relative to base branch
2. Read summaries of related artifacts
3. Generate the context.md file

Examples

Sync a Specific Change

superspec sync add-user-auth

Sync All Active Changes

superspec sync

Specify Base Branch

superspec sync add-user-auth --base develop

Skip git diff Collection

superspec sync add-user-auth --no-git

Generated context.md

---
change: add-user-auth
synced_at: 2026-01-15T10:30:00Z
base_branch: main
---

## Change Overview

This change implements user authentication...

## Current Status

- proposal.md: Ready
- spec.md: Ready
- tasks.md: In Progress (3/5 complete)

## Git Changes

### New Files
- src/auth/middleware.ts
- src/auth/jwt.ts

### Modified Files
- src/routes/index.ts
- src/config/index.ts

### Git Diff

```diff
diff --git a/src/auth/middleware.ts b/src/auth/middleware.ts
new file mode 100644
...

Pending Tasks

• [ ] Task 4: Implement token refresh
• [ ] Task 5: Add tests

## Used with /ss-resume

The `context.md` generated by `sync` is used for AI assistant context restoration:

You: /ss-resume AI: → Runs superspec sync → Reads context.md → Understands current progress → Continues unfinished work

## Workflow Suggestions

### During Development

```bash
# Sync after significant progress
superspec sync

Before Committing

# Ensure context.md is up to date
superspec sync
git add .
git commit -m "WIP: partial implementation"

Switching Tasks

# Sync current change
superspec sync current-change

# Switch to another change
git checkout other-branch
superspec sync other-change

Notes

1. Git repository: Must be run inside a git repository
2. Base branch: Ensure the base branch exists
3. Auto-detection: If not specified, automatically detects main or master
4. Zero AI tokens: This is a pure CLI operation, no AI tokens consumed