---
description: "View version history and manage design document revisions"
category: "version-control"
priority: "P3"
dependencies: ["version-manager.ps1"]
---

# Command: version

**Purpose**: View version history, compare changes, and manage design document revisions via Git integration

**Category**: Version Control - History & Management

**Related Commands**: 
- `export-design` - Export specific versions of designs
- `iterate-design` - Create new versions through iteration

---

## Command Syntax

```bash
/designfast:version --action=<history|status|diff|rollback> [--file=<path>] [--commit=<hash>]
```

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--action` | enum | ✅ Yes | - | Action: `history`, `status`, `diff`, or `rollback` |
| `--file` | path | ❌ No | all | Specific file to view history for (relative to workspace) |
| `--commit` | hash | ❌ No | - | Git commit hash for diff/rollback operations |
| `--limit` | number | ❌ No | 10 | Maximum number of history entries to display |

---

## Actions

### 1. History - View Version Timeline

**Action**: `--action=history`

**Purpose**: Display chronological version history of design documents

**Example**:
```bash
/designfast:version --action=history --file=designs/dashboard.json --limit=20
```

**Output**:
```
Version History: designs/dashboard.json
========================================

[1] 2025-11-10 15:30:45 (abc123f)
    ✓ Update prototype: Dashboard redesign
    Files: 1 changed, 15 insertions(+), 8 deletions(-)

[2] 2025-11-10 14:20:30 (def456a)
    ✓ Create design system: Corporate Design
    Files: 3 changed, 120 insertions(+)

[3] 2025-11-10 12:15:00 (789bcd2)
    ✓ Parse requirements for project: dashboard-v2
    Files: 2 changed, 45 insertions(+)

Total versions: 3
```

---

### 2. Status - Current Workspace State

**Action**: `--action=status`

**Purpose**: Show modified files and uncommitted changes in workspace

**Example**:
```bash
/designfast:version --action=status
```

**Output**:
```
Workspace Status
================

Modified Files:
  M  workspace/designs/project-abc.json
  M  workspace/prototypes/dashboard/index.html

Untracked Files:
  ?? workspace/designs/new-feature.md

Staged Changes:
  (none)

Tip: Changes are auto-committed on save. Manual commits available via version-manager.ps1
```

---

### 3. Diff - Compare Versions

**Action**: `--action=diff`

**Purpose**: Show differences between current version and specific commit

**Example**:
```bash
/designfast:version --action=diff --file=designs/dashboard.json --commit=abc123f
```

**Output**:
```
Diff: designs/dashboard.json (current vs abc123f)
=================================================

@@ components.header @@
- "backgroundColor": "#FFFFFF"
+ "backgroundColor": "#F3F4F6"

@@ components.sidebar @@
+ "width": "280px"
  "position": "fixed"

Summary: 2 changes (1 modified, 1 added)
```

---

### 4. Rollback - Restore Previous Version

**Action**: `--action=rollback`

**Purpose**: Restore file to previous version from commit history

**Example**:
```bash
/designfast:version --action=rollback --file=designs/dashboard.json --commit=def456a
```

**Output**:
```
⚠ Rollback Confirmation Required
================================

File: designs/dashboard.json
Target: def456a (2025-11-10 14:20:30)
Commit: "Create design system: Corporate Design"

Current changes will be overwritten.

Proceed with rollback? [Y/n]: Y

✓ File restored successfully
  Restored from: def456a
  Backup created: designs/dashboard.json.backup-2025-11-10-153045
```

---

## Agent Orchestration

### Primary Agent
**design-director** - Coordinates version operations and user confirmations

### Execution Flow

```
User Command
    ↓
design-director validates action
    ↓
version-manager.ps1 invoked
    ├─→ History: git log --oneline --follow {file}
    ├─→ Status: git status --short
    ├─→ Diff: git diff {commit}..HEAD {file}
    └─→ Rollback: git checkout {commit} -- {file}
    ↓
Formatted output returned to user
```

### Error Handling

| Error Code | Condition | Resolution |
|------------|-----------|------------|
| `ERR_VER_001` | Git not initialized | Run `version-manager.ps1 -Action Init` |
| `ERR_VER_002` | File not in version control | File hasn't been saved yet (no auto-commit) |
| `ERR_VER_003` | Invalid commit hash | Use `--action=history` to see valid commits |
| `ERR_VER_004` | Rollback canceled | User declined confirmation prompt |
| `ERR_VER_005` | Git unavailable | Install Git to enable version control |

---

## Examples

### Example 1: View Complete Project History

**Scenario**: Review all changes made to project design file

```bash
/designfast:version --action=history --file=designs/e-commerce-redesign.json --limit=50
```

**Output**:
```
Version History: designs/e-commerce-redesign.json
==================================================

[1] 2025-11-10 16:45:00 (aaa111b) - HEAD
    ✓ Update prototype: Add checkout flow
    
[2] 2025-11-10 15:30:00 (bbb222c)
    ✓ Auto-save: e-commerce-redesign.json
    
[3] 2025-11-10 14:00:00 (ccc333d)
    ✓ Create design system: E-commerce Design
    
[4] 2025-11-10 12:30:00 (ddd444e)
    ✓ Parse requirements for project: e-commerce-redesign

Total versions: 4
Current HEAD: aaa111b
```

---

### Example 2: Check Workspace Status

**Scenario**: See what files have been modified but not yet committed

```bash
/designfast:version --action=status
```

**Output**:
```
Workspace Status
================

Modified Files:
  M  workspace/designs/dashboard-v3.json (modified 2 minutes ago)
  M  workspace/prototypes/admin/styles.css (modified 5 minutes ago)

All changes will be auto-committed on next save operation.
```

---

### Example 3: Compare Current vs Previous Version

**Scenario**: Review changes made in last iteration

```bash
/designfast:version --action=diff --file=designs/dashboard.json --commit=HEAD~1
```

**Output**:
```
Diff: designs/dashboard.json (current vs HEAD~1)
================================================

Added:
+ "darkMode": true
+ "components.theme-toggle": { ... }

Modified:
~ "colors.primary": "#3B82F6" → "#2563EB"

Removed:
- "legacySupport": true

Summary: 3 changes (1 added, 1 modified, 1 removed)
```

---

### Example 4: Rollback to Previous Version

**Scenario**: Undo recent changes by restoring earlier version

```bash
/designfast:version --action=rollback --file=prototypes/dashboard.html --commit=abc123f
```

**Interactive Flow**:
```
⚠ Rollback Confirmation
======================

File: prototypes/dashboard.html
Target: abc123f (2025-11-10 10:30:00)
Commit: "Create prototype: Dashboard v1"

This will discard uncommitted changes.
A backup will be created automatically.

Proceed? [Y/n]: Y

✓ Rollback successful
  File restored from: abc123f
  Backup saved to: prototypes/dashboard.html.backup-2025-11-10-164500
  
Tip: Use --action=history to see all available versions
```

---

## Success Criteria

- [X] Command accepts all action types (history, status, diff, rollback)
- [X] History displays chronological commits with timestamps and messages
- [X] Status shows modified/untracked files accurately
- [X] Diff highlights added/modified/removed content clearly
- [X] Rollback requires user confirmation for safety
- [X] Rollback creates automatic backups before overwriting
- [X] Returns clear error messages when Git unavailable
- [X] Execution time < 2 seconds for typical operations
- [X] Compatible with standard Git workflows (CLI, GUI clients)

---

## Constitutional Compliance

### File-Based Workflow
✅ Version history backed by Git repository  
✅ All versions accessible via standard Git tools  
✅ No external database dependencies

### Agent Architecture
✅ design-director orchestrates version operations  
✅ Delegates to version-manager.ps1 for Git interactions  
✅ User confirmations for destructive operations (rollback)

### Performance Standards
✅ History retrieval < 2 seconds for 100+ commits  
✅ Status checks < 1 second  
✅ Diff operations < 1 second for typical files

### Safety & Reliability
✅ Automatic backups before rollback  
✅ Confirmation prompts for destructive actions  
✅ Non-destructive operations (history, status, diff) never modify files

---

## Implementation Notes

### PowerShell Script Integration

This command invokes `src/scripts/version-manager.ps1`:

```powershell
& "$PSScriptRoot\..\scripts\version-manager.ps1" `
    -Action $Action `
    -FilePath $FilePath `
    -CommitHash $CommitHash
```

### Git Integration Patterns

**History Retrieval**:
```powershell
git log --oneline --follow --format="%h|%ai|%s" -- $FilePath
```

**Status Check**:
```powershell
git status --short --untracked-files=all
```

**Diff Generation**:
```powershell
git diff $CommitHash..HEAD -- $FilePath
```

**Rollback Execution**:
```powershell
# Create backup first
Copy-Item $FilePath "$FilePath.backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
# Restore from commit
git checkout $CommitHash -- $FilePath
```

### Auto-Commit Integration

Works seamlessly with FR-012 auto-commit hooks:
- Every save operation creates version history entry
- Manual commits available via version-manager.ps1 directly
- History includes both auto-commits and manual commits

---

## Related Documentation

- **FR-012**: Version management specification with Git integration
- **version-manager.ps1**: PowerShell Git wrapper implementation
- **common.ps1**: Invoke-DesignAutoCommit hook function

---

## Changelog

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-11-10 | Initial version command specification with 4 actions (history/status/diff/rollback) |

---

**Last Updated**: 2025-11-10  
**Specification Status**: ✅ Complete  
**Implementation Status**: 🔄 In Progress (Phase 8 - T082)