claudetools/.claude/commands/README.md

# Claude Code Commands (also available to Grok)

Custom commands that extend the AI's capabilities (Claude Code or Grok).

These live in `.claude/commands/*.md`. For Grok coexistence, thin native wrappers exist in `.grok/skills/<name>/SKILL.md` (with `name:` frontmatter so `/save`, `/rmm` etc. work as first-class Grok slash commands via project skill discovery). The wrappers delegate to these files (read them at runtime + adapt tool names). Single source of truth remains here. See `.grok/README.md` for details.

## Available Commands

### `/snapshot` - Quick Context Save

Save conversation context on-demand without requiring a git commit.

**Usage:**
```bash
/snapshot
/snapshot "Custom title"
/snapshot --important
/snapshot --offline
```

**When to use:**
- Save progress without committing code
- Capture important discussions
- Remember exploratory changes
- Switching contexts/machines
- Multiple times per hour

**Documentation:** `snapshot.md`
**Quick Start:** `.claude/SNAPSHOT_QUICK_START.md`

---

### `/checkpoint` - Full Git + Context Save

Create git commit AND save context to database.

**Usage:**
```bash
/checkpoint
```

**When to use:**
- Code is ready to commit
- Reached stable milestone
- Completed feature/fix
- End of work session
- Once or twice per feature

**Documentation:** `checkpoint.md`

---

### `/sync` - Cross-Machine Context Sync

Synchronize queued contexts across machines.

**Usage:**
```bash
/sync
```

**When to use:**
- Manually trigger sync
- After offline work
- Before switching machines
- Check queue status

**Documentation:** `sync.md`

---

### `/create-spec` - App Specification

Create comprehensive application specification for AutoCoder.

**Usage:**
```bash
/create-spec
```

**When to use:**
- Starting new project
- Documenting existing app
- Preparing for AutoCoder
- Architecture planning

**Documentation:** `create-spec.md`

---

## Command Comparison

| Command | Git Commit | Context Save | Speed | Use Case |
|---------|-----------|-------------|-------|----------|
| `/snapshot` | No | Yes | Fast | Save progress |
| `/checkpoint` | Yes | Yes | Slower | Save code + context |
| `/sync` | No | No | Fast | Sync contexts |
| `/create-spec` | No | No | Medium | Create spec |

## Common Workflows

### Daily Development

```
Morning:
  - Start work
  - /snapshot Research phase

Mid-day:
  - Complete feature
  - /checkpoint

Afternoon:
  - More work
  - /snapshot Progress update

End of day:
  - /checkpoint
  - /sync
```

### Research Heavy

```
Research:
  - /snapshot multiple times
  - Capture decisions

Implementation:
  - /checkpoint for features
  - Link code to research
```

### New Project

```
Planning:
  - /create-spec
  - /snapshot Architecture decisions

Development:
  - /snapshot frequently
  - /checkpoint for milestones
```

## Setup

**Required for context commands:**
```bash
bash scripts/setup-context-recall.sh
```

This configures:
- JWT authentication token
- API endpoint URL
- Project ID
- Context recall settings

**Configuration file:** `.claude/context-recall-config.env`

## Documentation

**Quick References:**
- `.claude/SNAPSHOT_QUICK_START.md` - Snapshot guide
- `.claude/SNAPSHOT_VS_CHECKPOINT.md` - When to use which
- `.claude/CONTEXT_RECALL_QUICK_START.md` - Context recall system

**Full Documentation:**
- `snapshot.md` - Complete snapshot docs
- `checkpoint.md` - Complete checkpoint docs
- `sync.md` - Complete sync docs
- `create-spec.md` - Complete spec creation docs

**Implementation:**
- `SNAPSHOT_IMPLEMENTATION.md` - Technical details

## Testing

**Test snapshot:**
```bash
bash scripts/test-snapshot.sh
```

**Test context recall:**
```bash
bash scripts/test-context-recall.sh
```

**Test sync:**
```bash
bash .claude/hooks/sync-contexts
```

## Troubleshooting

**Commands not working:**
```bash
# Check configuration
cat .claude/context-recall-config.env

# Verify executable
ls -l .claude/commands/

# Make executable
chmod +x .claude/commands/*
```

**Context not saving:**
```bash
# Check API connection
curl -I http://172.16.3.30:8001/api/health

# Regenerate token
bash scripts/setup-context-recall.sh

# Check logs
tail -f .claude/context-queue/sync.log
```

**Project ID issues:**
```bash
# Set manually
git config --local claude.projectid "$(uuidgen)"

# Verify
git config --local claude.projectid
```

## Adding Custom Commands

**Structure:**
```
.claude/commands/
├── command-name           # Executable bash script
└── command-name.md        # Documentation
```

**Template:**
```bash
#!/bin/bash
# Command description

set -euo pipefail

# Load configuration
source .claude/context-recall-config.env

# Command logic here
echo "Hello from custom command"
```

**Make executable:**
```bash
chmod +x .claude/commands/command-name
```

**Test:**
```bash
bash .claude/commands/command-name
```

**Use in Claude Code:**
```
/command-name
```

## Command Best Practices

**Snapshot:**
- Use frequently (multiple per hour)
- Descriptive titles
- Don't over-snapshot (meaningful moments)
- Tag auto-extraction works best with good context

**Checkpoint:**
- Only checkpoint clean state
- Good commit messages
- Group related changes
- Don't checkpoint too often

**Sync:**
- Run before switching machines
- Run after offline work
- Check queue status periodically
- Auto-syncs on most operations

**Create-spec:**
- Run once per project
- Update when architecture changes
- Include all important details
- Use for AutoCoder integration

## Advanced Usage

**Snapshot with importance:**
```bash
/snapshot --important "Critical architecture decision"
```

**Offline snapshot:**
```bash
/snapshot --offline "Working without network"
```

**Checkpoint with message:**
```bash
/checkpoint
# Follow prompts for commit message
```

**Sync specific project:**
```bash
# Edit sync script to filter by project
bash .claude/hooks/sync-contexts
```

## Integration

**With Context Recall:**
- Commands save to database
- Automatic recall in future sessions
- Cross-machine continuity
- Searchable knowledge base

**With AutoCoder:**
- `/create-spec` generates AutoCoder input
- Commands track project state
- Context feeds AutoCoder sessions
- Complete audit trail

**With Git:**
- `/checkpoint` creates commits
- `/snapshot` preserves git state
- No conflicts with git workflow
- Clean separation of concerns

## Support

**Questions:**
- Check documentation in this directory
- See `.claude/CLAUDE.md` for project overview
- Review test scripts for examples

**Issues:**
- Verify configuration
- Check API connectivity
- Review error messages
- Test with provided scripts

**Updates:**
- Update via git pull
- Regenerate config if needed
- Test after updates
- Check for breaking changes

---

**Quick command reference:**
- `/snapshot` - Quick save (no commit)
- `/checkpoint` - Full save (with commit)
- `/sync` - Sync contexts
- `/create-spec` - Create app spec

**Setup:** `bash scripts/setup-context-recall.sh`
**Test:** `bash scripts/test-snapshot.sh`
**Docs:** Read the `.md` file for each command