@jive-ai/cli 0.0.25 → 0.0.30

package/docs/sync.md

@@ -1,673 +0,0 @@
-# Synchronization Commands
-
-Synchronization commands help you keep your local project resources in sync with your team's shared resources on the Jive platform.
-
-## Overview
-
-Jive provides commands to:
-- Synchronize all team resources (subagents and MCP servers) to your local project
-- Check the sync status of your project
-- View which team you're currently working with
-
-## Commands
-
-### `jive sync`
-
-Synchronize all resources between your local project and the team.
-
-**Usage:**
-```bash
-jive sync [--dry-run]
-```
-
-**Options:**
-- `--dry-run` - Show what would be changed without making changes (not fully implemented)
-
-**Requirements:**
-- Must be authenticated
-- Must be in a Jive-initialized project (has active team)
-
-**Process:**
-1. **Pull subagents:**
-   - Downloads all team subagents to `.claude/agents/`
-   - Skips files that already exist locally (no overwrite)
-   - Adds `jive-id` to frontmatter for tracking
-
-2. **Pull MCP servers:**
-   - Downloads all team MCP servers to `.mcp.json`
-   - Merges with local servers (preserves local-only servers)
-   - Creates backup at `.mcp.json.backup`
-
-3. **Update sync metadata:**
-   - Updates `.jive/sync.json` with sync timestamp
-   - Records last sync time
-
-**Output:**
-```bash
-jive sync
-```
-```
-Synchronizing with team 'My Team'...
-
-Pulling subagents...
-✓ code-reviewer.md
-✓ bug-fixer.md
-⊘ test-writer.md (already exists)
-
-Pulling MCP servers...
-Creating backup: .mcp.json.backup
-✓ weather-api
-✓ file-system
-✓ database
-
-Sync complete!
-
-Summary:
-- Downloaded 2 subagents, skipped 1
-- Merged 3 MCP servers
-- Last sync: 2025-01-15 10:30:00
-
-Next steps:
-1. Restart Claude Code to apply changes
-2. Review new subagents in .claude/agents/
-3. Check updated .mcp.json configuration
-```
-
-**What Gets Synced:**
-
-| Resource | Action | Notes |
-|----------|--------|-------|
-| Subagents | Pull | Skips existing files |
-| MCP Servers | Pull with merge | Preserves local-only servers |
-| jive-mcp server | Preserved | Never overwritten |
-| Local-only subagents | Preserved | Without `jive-id` |
-
-**Sync Metadata:**
-
-After sync, `.jive/sync.json` is updated:
-```json
-{
-  "lastSync": "2025-01-15T10:30:00.000Z",
-  "subagents": {
-    "code-reviewer": {
-      "lastModified": "2025-01-14T15:20:00.000Z",
-      "jiveId": "sub-123"
-    }
-  },
-  "mcpServers": {
-    "weather-api": {
-      "lastModified": "2025-01-14T12:00:00.000Z",
-      "jiveId": "mcp-456"
-    }
-  }
-}
-```
-
-**Notes:**
-- Safe to run multiple times (idempotent)
-- Won't overwrite local changes to existing subagents
-- Use `jive subagents pull --overwrite` for force update
-- Use `jive mcp pull` (without merge) for full replacement
-- Restart Claude Code after sync to apply MCP server changes
-
-**Use Cases:**
-- Getting latest team resources after joining a project
-- Updating to newest versions shared by team
-- Daily sync to stay current with team
-- After switching teams to get new team's resources
-
-**Error Conditions:**
-- Not authenticated
-- Project not initialized
-- Network connectivity issues
-- File system permission errors
-
-**Implementation:** `src/commands/sync.ts` (syncCommand)
-
----
-
-### `jive status`
-
-Show the sync status of your local project.
-
-**Usage:**
-```bash
-jive status
-```
-
-**Requirements:**
-- Must be in a Jive-initialized project
-
-**Process:**
-1. Reads `.jive/config.json` for active team
-2. Reads `.jive/sync.json` for sync metadata
-3. Displays project status information
-
-**Output:**
-```bash
-jive status
-```
-```
-Jive Project Status
-
-Active Team: My Team (team-abc123)
-Last Sync: 2025-01-15 10:30:00 (2 hours ago)
-
-To view team resources:
-- Subagents: jive subagents list
-- MCP Servers: jive mcp list
-
-To sync latest changes:
-- jive sync
-```
-
-**Detailed Status Information:**
-
-The status command shows:
-- **Active Team:** Which team this project is connected to
-- **Team ID:** Unique identifier for the team
-- **Last Sync:** When resources were last synced with the team
-- **Time Ago:** Relative time since last sync (e.g., "2 hours ago")
-
-**Suggested Commands:**
-
-Based on status, the command suggests:
-- `jive subagents list` - View team subagents
-- `jive mcp list` - View team MCP servers
-- `jive sync` - Sync latest changes
-- `jive team switch` - Switch to different team
-
-**Notes:**
-- Read-only command (doesn't modify anything)
-- Helps you understand current project state
-- Quick way to check which team you're working with
-- Shows when you last synced
-
-**Error Conditions:**
-- Project not initialized (displays "Project not initialized")
-- Missing config files (displays "Configuration missing")
-
-**Implementation:** `src/commands/sync.ts` (statusCommand)
-
----
-
-## Synchronization Workflows
-
-### Initial Project Setup
-
-**New team member joins:**
-
-1. **Authenticate:**
-   ```bash
-   jive login
-   ```
-
-2. **Initialize project:**
-   ```bash
-   cd project-directory
-   jive init
-   ```
-   Select the team when prompted.
-
-3. **Sync team resources:**
-   ```bash
-   jive sync
-   ```
-
-4. **Check status:**
-   ```bash
-   jive status
-   ```
-
-5. **Restart Claude Code**
-
-### Daily Workflow
-
-**Start of day:**
-
-1. **Check status:**
-   ```bash
-   jive status
-   ```
-
-2. **Sync latest changes:**
-   ```bash
-   jive sync
-   ```
-
-3. **Restart Claude Code** (if MCP servers changed)
-
-**During work:**
-
-1. **Create/modify resources locally**
-2. **Push changes to team:**
-   ```bash
-   jive subagents push
-   jive mcp push
-   ```
-
-**End of day:**
-
-1. **Final sync:**
-   ```bash
-   jive sync
-   ```
-
-### Switching Teams
-
-**Change to different team:**
-
-1. **Check current status:**
-   ```bash
-   jive status
-   ```
-
-2. **Switch team:**
-   ```bash
-   jive team switch
-   ```
-
-3. **Sync new team's resources:**
-   ```bash
-   jive sync
-   ```
-
-4. **Verify new status:**
-   ```bash
-   jive status
-   ```
-
-5. **Restart Claude Code**
-
-### Handling Conflicts
-
-**Local changes vs team changes:**
-
-**Scenario:** You modified `code-reviewer.md` locally, team also updated it.
-
-**Approach 1: Keep local changes**
-```bash
-# Don't sync (local version remains)
-# Push your version to team
-jive subagents push -m "My improvements"
-```
-
-**Approach 2: Get team changes**
-```bash
-# Backup local version
-cp .claude/agents/code-reviewer.md .claude/agents/code-reviewer.md.backup
-
-# Force pull team version
-jive subagents pull --overwrite
-
-# Manually merge changes
-# Edit code-reviewer.md to combine both versions
-
-# Push merged version
-jive subagents push -m "Merged team updates with local changes"
-```
-
-**Approach 3: Keep both versions**
-```bash
-# Rename local version
-mv .claude/agents/code-reviewer.md .claude/agents/code-reviewer-v2.md
-
-# Pull team version
-jive subagents pull
-
-# Now you have both:
-# - code-reviewer.md (team version)
-# - code-reviewer-v2.md (your version)
-
-# Push your version as new subagent
-jive subagents push
-```
-
-## Sync Strategies
-
-### Conservative Sync (Preserve Local)
-
-**Goal:** Keep all local changes, get new team resources only
-
-```bash
-# Sync without overwriting
-jive sync
-
-# Or manually:
-jive subagents pull          # Skips existing
-jive mcp pull --merge        # Merges with local
-```
-
-**Best for:**
-- Active development with local changes
-- Testing local modifications
-- Paranoid about losing work
-
-### Aggressive Sync (Match Team)
-
-**Goal:** Make local identical to team
-
-```bash
-# Full overwrite
-jive subagents pull --overwrite
-jive mcp pull                # Replace (no --merge)
-
-# Or detach and re-init:
-jive detach
-jive init
-jive sync
-```
-
-**Best for:**
-- Fresh start with team resources
-- Fixing corrupted local state
-- New team member setup
-
-### Selective Sync
-
-**Goal:** Sync specific resources only
-
-```bash
-# Just subagents
-jive subagents pull
-
-# Just MCP servers
-jive mcp pull
-
-# Specific subagent (pull then overwrite)
-jive subagents pull --overwrite
-# (affects all subagents currently)
-```
-
-**Best for:**
-- Updating one resource type
-- Bandwidth-conscious environments
-- Incremental updates
-
-## Sync State Management
-
-### .jive/sync.json
-
-**Purpose:** Tracks local sync state
-
-```json
-{
-  "lastSync": "2025-01-15T10:30:00.000Z",
-  "subagents": {
-    "code-reviewer": {
-      "lastModified": "2025-01-14T15:20:00.000Z",
-      "jiveId": "sub-123",
-      "hash": "abc123..."
-    },
-    "local-only-agent": {
-      "lastModified": "2025-01-15T09:00:00.000Z"
-      // No jiveId - local-only
-    }
-  },
-  "mcpServers": {
-    "weather-api": {
-      "lastModified": "2025-01-14T12:00:00.000Z",
-      "jiveId": "mcp-456"
-    }
-  }
-}
-```
-
-**Fields:**
-- `lastSync` - Timestamp of last successful sync
-- `jiveId` - Platform ID (indicates synced resource)
-- `lastModified` - When resource was last changed
-- `hash` - Content hash for change detection (future)
-
-**Notes:**
-- Should be in `.gitignore` (local state only)
-- Automatically updated by sync commands
-- Used to detect changes and conflicts
-
-### Frontmatter jive-id
-
-**Subagent tracking:**
-
-```markdown
----
-name: code-reviewer
-description: Reviews code
-jive-id: "sub-123"
----
-
-Prompt content...
-```
-
-**Purpose:**
-- Links local file to team resource
-- Enables updates instead of duplicates
-- Tracks which files are synced
-
-**Behavior:**
-- **With `jive-id`:** `jive subagents push` updates existing
-- **Without `jive-id`:** `jive subagents push` creates new
-- Added automatically by `jive init` and `jive subagents pull`
-
-## Automation
-
-### Git Hooks
-
-**Pre-commit hook:**
-```bash
-#!/bin/bash
-# .git/hooks/pre-commit
-
-# Check if team resources are out of sync
-if jive status | grep -q "Last Sync.*days ago"; then
-  echo "Warning: Team resources not synced recently"
-  echo "Run 'jive sync' to update"
-  # Don't block commit, just warn
-fi
-```
-
-**Post-merge hook:**
-```bash
-#!/bin/bash
-# .git/hooks/post-merge
-
-# Auto-sync after pulling from git
-echo "Running jive sync..."
-jive sync
-echo "Restart Claude Code to apply changes"
-```
-
-### CI/CD Integration
-
-**Verify sync status in CI:**
-```yaml
-# .github/workflows/check-jive.yml
-name: Check Jive Sync
-
-on: [push, pull_request]
-
-jobs:
-  check-sync:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Setup Node
-        uses: actions/setup-node@v2
-      - name: Install Jive CLI
-        run: npm install -g jive-cli
-      - name: Check Status
-        run: jive status
-```
-
-### Scheduled Sync
-
-**Cron job (daily sync):**
-```bash
-# Add to crontab
-0 9 * * * cd /path/to/project && jive sync
-```
-
-**Shell script:**
-```bash
-#!/bin/bash
-# sync-jive-projects.sh
-
-PROJECTS=(
-  "/path/to/project1"
-  "/path/to/project2"
-)
-
-for project in "${PROJECTS[@]}"; do
-  echo "Syncing $project..."
-  cd "$project"
-  jive sync
-done
-```
-
-## Troubleshooting
-
-### Out of Sync
-
-**Symptoms:**
-- Team members have different resources
-- Missing subagents or MCP servers
-
-**Solutions:**
-```bash
-# Check current status
-jive status
-
-# Sync to get latest
-jive sync
-
-# Force overwrite if needed
-jive subagents pull --overwrite
-jive mcp pull
-
-# Restart Claude Code
-```
-
-### Sync Fails
-
-**Symptoms:**
-- Network errors during sync
-- Partial sync completion
-
-**Solutions:**
-```bash
-# Retry sync
-jive sync
-
-# Check authentication
-jive login
-
-# Verify network connectivity
-jive doctor
-
-# Check project initialization
-jive init
-```
-
-### Last Sync Unknown
-
-**Symptoms:**
-- Status shows no last sync time
-- Missing `.jive/sync.json`
-
-**Solutions:**
-```bash
-# Re-initialize to fix
-jive init
-
-# Or manually sync
-jive sync
-```
-
-### Conflicting Changes
-
-**Symptoms:**
-- Local and remote versions differ
-- Unsure which to keep
-
-**Solutions:**
-1. **Backup local:**
-   ```bash
-   cp -r .claude/agents .claude/agents.backup
-   ```
-
-2. **Pull team version:**
-   ```bash
-   jive subagents pull --overwrite
-   ```
-
-3. **Compare and merge:**
-   ```bash
-   diff -r .claude/agents.backup .claude/agents
-   ```
-
-4. **Push final version:**
-   ```bash
-   jive subagents push -m "Merged local and team changes"
-   ```
-
-## Best Practices
-
-### Regular Syncing
-
-- Sync at least daily
-- Sync before starting work
-- Sync after team updates
-- Sync before pushing changes
-
-### Communication
-
-- Notify team before major changes
-- Use descriptive push messages
-- Document breaking changes
-- Coordinate on sensitive updates
-
-### Version Control
-
-- Commit `.claude/agents/*.md` to git
-- Commit `.mcp.json` to git
-- **Don't commit:**
-  - `.jive/config.json` (team-specific)
-  - `.jive/sync.json` (local state)
-  - `.claude/plugins/` (generated)
-  - `.mcp.json.backup` (temporary)
-
-### Conflict Resolution
-
-- Pull before push
-- Test changes locally first
-- Use descriptive change messages
-- Keep backups of important prompts
-
-## Related Commands
-
-- [`jive init`](./init.md#jive-init) - Initialize project (sets up sync)
-- [`jive subagents pull`](./subagents.md#jive-subagents-pull) - Pull subagents only
-- [`jive subagents push`](./subagents.md#jive-subagents-push) - Push subagents
-- [`jive mcp pull`](./mcp.md#jive-mcp-pull) - Pull MCP servers only
-- [`jive mcp push`](./mcp.md#jive-mcp-push) - Push MCP servers
-- [`jive team switch`](./team.md#jive-team-switch) - Change active team
-- [`jive doctor`](./init.md#jive-doctor) - Verify sync configuration
-
-## Implementation Details
-
-**Source Files:**
-- Main implementation: `src/commands/sync.ts`
-- Subagent sync: `src/commands/subagents.ts`
-- MCP sync: `src/commands/mcp.ts`
-- Config helpers: `src/lib/config.ts`
-
-**Key Functions:**
-- `syncCommand()` - Main sync orchestration
-- `statusCommand()` - Display sync status
-- `updateSyncMetadata()` - Update `.jive/sync.json`
-- `getLastSyncTime()` - Read last sync timestamp
-- `shouldSync()` - Determine if sync needed (future)
-
-**API Integration:**
-- Sync uses same endpoints as pull commands
-- No dedicated sync endpoint (composite operation)
-- Pull operations are idempotent and safe to repeat