2508 L4 Advanced Commands 45889193

L4-TASK-001: /zerg:git Command

Objective

Implement git operations with intelligent commits and finish workflow.

Context

Depends on: L1-TASK-001 (Worktree Manager)

The git command provides smart git operations including the critical "finish" workflow for completing development branches.

Files to Create

.claude/commands/
└── zerg:git.md

.zerg/
└── git_ops.py

Actions

commit

Intelligent commit with auto-generated conventional message:

/zerg:git --action commit [--push]

branch

Branch management:

/zerg:git --action branch --name feature/auth

merge

Intelligent merge with conflict detection:

/zerg:git --action merge --branch feature/auth --strategy squash

sync

Synchronize with remote:

/zerg:git --action sync

history

Analyze and generate changelog:

/zerg:git --action history --since v1.0.0

finish (CRITICAL)

Complete development branch with structured options:

/zerg:git --action finish [--base main]

Finish Workflow:

Implementation complete. All tests passing. What would you like to do?

1. Merge back to main locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Finish Logic:

def finish_branch(branch: str, base: str = "main") -> FinishResult:
    # Step 1: Verify tests pass (REQUIRED)
    test_result = run_project_tests()
    if not test_result.passed:
        return FinishResult(
            blocked=True,
            reason=f"Tests failing ({test_result.failures} failures)"
        )
    
    # Step 2: Present options
    choice = present_finish_options(branch, base)
    
    # Step 3: Execute choice
    if choice == 1:  # Merge locally
        checkout(base)
        merge(branch, no_ff=True)
        verify_tests()
        delete_branch(branch)
        cleanup_worktree(branch)
        
    elif choice == 2:  # Create PR
        push(branch, set_upstream=True)
        create_pr(title, body)
        
    elif choice == 3:  # Keep as-is
        pass
        
    elif choice == 4:  # Discard
        if confirm_discard():
            delete_branch(branch, force=True)
            cleanup_worktree(branch)

Verification

cd .zerg && python -c "
from git_ops import GitOps
go = GitOps()
print('Available actions:', go.available_actions())
"

L4-TASK-002: /zerg:build Command

Objective

Implement build orchestration with error recovery.

Files to Create

.claude/commands/
└── zerg:build.md

.zerg/
└── build.py

Capabilities

1. Auto-detect: npm, cargo, make, gradle, go
2. Error Recovery: Classify and retry with fixes
3. Retry Logic: Up to 3 attempts
4. Build Report: Timing, artifact sizes
5. Watch Mode: Rebuild on changes

Error Recovery Categories

• missing_dependency: Run install command
• type_error: Suggest fix
• resource_exhaustion: Reduce parallelism
• network_timeout: Retry with backoff

Usage

/zerg:build [--target all]
            [--mode dev|staging|prod]
            [--clean]
            [--watch]
            [--retry 3]

L4-TASK-003: /zerg:session Command

Objective

Implement session save/load for multi-session continuity.

Files to Create

.claude/commands/
└── zerg:session.md

.zerg/
└── session.py

Actions

save

/zerg:session --action save [--name my-session] [--compress]

Saves:

• Execution state
• Task progress
• Worker checkpoints
• Spec files

load

/zerg:session --action load --name my-session

list

/zerg:session --action list

delete

/zerg:session --action delete --name old-session

Session Manifest

{
  "name": "my-session",
  "created_at": "2025-01-25T12:00:00Z",
  "feature": "auth-system",
  "level": 2,
  "tasks_complete": 12,
  "tasks_total": 47,
  "checksums": {
    "state.json": "abc123",
    "task-graph.json": "def456"
  }
}

L4-TASK-004: /zerg:index Command

Objective

Implement project knowledge base generation.

Files to Create

.claude/commands/
└── zerg:index.md

.zerg/
├── indexer.py
└── index/              # Index output

Capabilities

1. Structure Scan: Project file tree
2. Symbol Extraction: Functions, classes, types
3. Dependency Graph: Import relationships
4. Documentation: Docstrings, README
5. Vector Embeddings: Optional semantic search

Index Output

{
  "files": [
    {
      "path": "src/auth/types.ts",
      "language": "typescript",
      "symbols": [
        {"name": "AuthUser", "type": "interface", "line": 10},
        {"name": "authenticate", "type": "function", "line": 25}
      ],
      "imports": ["../config", "jsonwebtoken"],
      "exports": ["AuthUser", "authenticate"]
    }
  ],
  "dependencies": {
    "src/auth/types.ts": ["src/config.ts"]
  }
}

Usage

/zerg:index [--format json|sqlite]
            [--embeddings]
            [--include "src/**"]
            [--exclude "node_modules"]

L4-TASK-005: /zerg:document Command

Objective

Implement documentation generation and maintenance.

Files to Create

.claude/commands/
└── zerg:document.md

.zerg/
└── document.py

Document Types

1. api: API reference from code
2. readme: Project README
3. architecture: System architecture
4. changelog: From git history

Usage

/zerg:document --type api [--output docs/api.md]
/zerg:document --type readme [--update]
/zerg:document --type architecture [--diagram]

Features

• Code structure analysis
• JSDoc/docstring extraction
• Mermaid diagram generation
• Update mode (preserve manual edits)

L4-TASK-006: /zerg:purge Command

Objective

Implement artifact and worktree cleanup (renamed from cleanup).

Files to Create

.claude/commands/
└── zerg:purge.md

.zerg/
└── purge.py

Targets

1. worktrees: Remove .zerg/worktrees/
2. logs: Remove .zerg/logs/
3. checkpoints: Remove .zerg/checkpoints/
4. metrics: Remove .zerg/metrics/
5. all: Everything above

Usage

/zerg:purge [--target worktrees|logs|all]
            [--preserve-specs]
            [--dry-run]
            [--force]

Safety

• Confirm before destructive actions
• Never delete .gsd/specs/ unless forced
• Dry-run shows what would be deleted