# Command Reference

> Complete documentation for all ZERG slash commands. Each command includes plain-language explanations, visual diagrams, and practical examples to help you understand not just how to use them, but why they exist.

- Skill: `tools-only/command-reference-3` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/command-reference-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/command-reference-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/command-reference-3

---

# Command Reference

Complete documentation for all ZERG slash commands. Each command includes plain-language explanations, visual diagrams, and practical examples to help you understand not just how to use them, but why they exist.

This guide assumes you know basic programming and git but are new to AI coding assistants and distributed task execution. Every command is explained with:

1. **What Is It?** - The concept in plain language
2. **Why Use It?** - The problem it solves
3. **How It Works** - Visual diagram of the flow
4. **Using It** - Command examples with expected output

Commands can be invoked in two ways:
- **Slash command**: `/zerg:rush --workers=5` (inside Claude Code)
- **CLI**: `zerg rush --workers=5` (from the terminal)

---

## Table of Contents

- [Global Flags](#global-flags)
- [Core Workflow](#core-workflow)
  - [/zerg:brainstorm](#zergbrainstorm)
  - [/zerg:design](#zergdesign)
  - [/zerg:init](#zerginit)
  - [/zerg:plan](#zergplan)
  - [/zerg:rush](#zergrush)
- [Monitoring and Control](#monitoring-and-control)
  - [/zerg:cleanup](#zergcleanup)
  - [/zerg:logs](#zerglogs)
  - [/zerg:merge](#zergmerge)
  - [/zerg:retry](#zergretry)
  - [/zerg:status](#zergstatus)
  - [/zerg:stop](#zergstop)
- [Quality and Analysis](#quality-and-analysis)
  - [/zerg:analyze](#zerganalyze)
  - [/zerg:build](#zergbuild)
  - [/zerg:refactor](#zergrefactor)
  - [/zerg:review](#zergreview)
  - [/zerg:security](#zergsecurity)
  - [/zerg:test](#zergtest)
- [Utilities](#utilities)
  - [/zerg:create-command](#zergcreate-command)
  - [/zerg:debug](#zergdebug)
  - [/zerg:git](#zerggit)
  - [/zerg:plugins](#zergplugins)
  - [/zerg:worker](#zergworker)
- [Documentation and AI](#documentation-and-ai)
  - [/zerg:document](#zergdocument)
  - [/zerg:estimate](#zergestimate)
  - [/zerg:explain](#zergexplain)
  - [/zerg:index](#zergindex)
  - [/zerg:select-tool](#zergselect-tool)
- [Exit Codes](#exit-codes)

---

## Global Flags

These flags apply to all ZERG commands when invoked via the CLI.

### Analysis Depth

Control how deeply ZERG thinks about your request. Higher depth means more thorough analysis but uses more tokens.

| Flag | Token Budget | When to Use |
|------|-------------|-------------|
| `--quick` | ~1K tokens | Simple, routine tasks |
| `--think` | ~4K tokens | Multi-step analysis |
| `--think-hard` | ~10K tokens | Architectural decisions |
| `--ultrathink` | ~32K tokens | Complex system design |

### Output and Efficiency

| Flag | Default | Description |
|------|---------|-------------|
| `--no-compact` | false | Disable compact output (verbose mode) |

### Behavioral Mode

| Flag | Default | Description |
|------|---------|-------------|
| `--mode` | auto | Override mode: `precision`, `speed`, `exploration`, `refactor`, `debug` |

### MCP Routing

| Flag | Default | Description |
|------|---------|-------------|
| `--mcp` | true | Enable MCP server auto-routing |
| `--no-mcp` | false | Disable all MCP server recommendations |

### Improvement Loops

| Flag | Default | Description |
|------|---------|-------------|
| `--no-loop` | false | Disable improvement loops |
| `--iterations` | config | Set max loop iterations |

### TDD Enforcement

| Flag | Default | Description |
|------|---------|-------------|
| `--tdd` | false | Enable red-green-refactor protocol |

### Standard Flags

| Flag | Short | Description |
|------|-------|-------------|
| `--verbose` | `-v` | Enable verbose output |
| `--quiet` | `-q` | Suppress non-essential output |
| `--version` | | Show version and exit |
| `--help` | | Show help message and exit |

---

## Core Workflow

The core workflow commands take you from an empty idea to working code through a structured process: initialize your project, discover what to build, capture requirements, design the architecture, and execute with parallel workers.

---

### /zerg:brainstorm

#### What Is It?

The brainstorm command helps you figure out what to build before you commit to building it. It is a structured discovery process that researches competitors, asks probing questions, and helps you crystallize vague ideas into concrete requirements.

Imagine you know you want to improve your authentication system but you are not sure exactly what needs fixing. Brainstorm researches how other systems handle authentication, asks you questions to uncover hidden requirements, and ultimately produces a prioritized list of features with GitHub issues ready to go.

#### Why Use It?

Starting to code without clear requirements leads to wasted effort. You build something, realize it is not what users need, and throw away work. Brainstorm front-loads the thinking so you build the right thing the first time.

The command also performs competitive research. It searches the web for how similar products solve the problem, identifies market gaps, and brings back insights you might not have discovered on your own. This is not just planning - it is strategic planning.

#### How It Works

```
+---------------------------------------------------------------------+
|                      /zerg:brainstorm                               |
+---------------------------------------------------------------------+
                              |
        Phase 1               v
    +-------------------------------------+
    |           RESEARCH                  |
    |  - Search competitors               |
    |  - Find market gaps                 |
    |  - Identify trends                  |
    +-------------------------------------+
                              |
        Phase 2               v
    +-------------------------------------+
    |       SOCRATIC DISCOVERY            |
    |  Round 1: Problem Space             |
    |  Round 2: Solution Space            |
    |  Round 3: Implementation Space      |
    +-------------------------------------+
                              |
        Phase 2.5-2.7         v
    +-------------------------------------+
    |         VALIDATION                  |
    |  - Trade-off exploration            |
    |  - Design checkpoints               |
    |  - YAGNI gate (filter extras)       |
    +-------------------------------------+
                              |
        Phase 3               v
    +-------------------------------------+
    |       ISSUE GENERATION              |
    |  - Create GitHub issues             |
    |  - Add acceptance criteria          |
    |  - Apply priority labels            |
    +-------------------------------------+
                              |
                              v
    +-------------------------------------+
    |  Output: Ranked recommendations     |
    |  -> /zerg:plan for top pick         |
    +-------------------------------------+
```

**What YAGNI gate means:** "You Aren't Gonna Need It" - features that sound nice but are not essential for the first version get deferred. This keeps scope tight.

#### Using It

**Basic brainstorm:**
```
/zerg:brainstorm user-authentication
```

ZERG researches and then asks questions:
```
ZERG: I found these patterns in competitor auth systems:
      - OAuth 2.0 with social login (Google, GitHub)
      - Magic link authentication (passwordless)
      - Hardware key support (WebAuthn)

ZERG: What authentication challenges are your users facing today?
YOU:  Password fatigue - they forget passwords and reset flows are slow.

ZERG: What's your user base like? Technical vs non-technical?
YOU:  Mix of both. Developers use our API directly, non-devs use the web app.

ZERG: What compliance requirements do you have?
YOU:  SOC 2 certification is coming up. We need audit logs.
```

**Single-question Socratic mode:**
```
/zerg:brainstorm user-auth --socratic
```

Instead of multiple questions at once, ZERG asks one question at a time and goes deeper:
```
ZERG: Let's start with the problem. What specific authentication
      issue is causing the most user friction right now?
YOU:  Password resets. Users do 50+ resets per day.

ZERG: That's significant. When users reset passwords, what's the
      longest step in your current flow?
YOU:  Email delivery. Sometimes takes 5+ minutes.
```

**Preview without creating issues:**
```
/zerg:brainstorm api-redesign --skip-research --dry-run
```

Output shows what would be created:
```
Would create 4 GitHub issues:

[P0] Implement rate limiting on public endpoints
     Labels: security, api

[P1] Add pagination to list endpoints
     Labels: api, breaking-change

[P2] Deprecate v1 endpoints
     Labels: api, maintenance
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--rounds` | integer | 3 | Number of Socratic discovery rounds (max: 5) |
| `--socratic` | boolean | false | Enable single-question mode |
| `--skip-research` | boolean | false | Skip competitive analysis |
| `--skip-issues` | boolean | false | Ideate only, don't create issues |
| `--dry-run` | boolean | false | Preview issues without creating |
| `--resume` | boolean | false | Resume previous session |

---

### /zerg:design

#### What Is It?

The design command transforms approved requirements into a technical architecture and a task graph that workers can execute in parallel. It is the bridge between "what to build" (requirements) and "how to build it" (implementation).

Think of it as an architect drawing blueprints from a client's wish list. The requirements say "I want a house with 3 bedrooms." The design specifies exactly which walls go where, how the plumbing connects, and in what order contractors should work so they do not step on each other.

#### Why Use It?

Parallel execution requires careful planning. If two workers try to edit the same file, you get merge conflicts. If a worker tries to use a function that does not exist yet, the task fails. The design command solves this by:

1. Breaking work into tasks with clear boundaries
2. Assigning exclusive file ownership (no conflicts possible)
3. Organizing tasks into dependency levels (Level 1 completes before Level 2 starts)

The output (task-graph.json) is what `/zerg:rush` executes. Good design means smooth execution.

#### How It Works

```
+---------------------------------------------------------------------+
|                         /zerg:design                                |
+---------------------------------------------------------------------+
                              |
        Phase 1               v
    +-------------------------------------+
    |      ARCHITECTURE DESIGN            |
    |  - Component analysis               |
    |  - Data flow mapping                |
    |  - Interface definitions            |
    |  - Key decisions documented         |
    +-------------------------------------+
                              |
        Phase 2               v
    +---------------------------------------------------------------------+
    |                   IMPLEMENTATION PLAN                               |
    |                                                                     |
    |  Level 1: Foundation     Level 2: Core      Level 3: Integration   |
    |  +------------------+   +--------------+   +-------------------+   |
    |  | types.ts         |   | auth.service |   | auth.routes       |   |
    |  | schema.py        |   | user.service |   | user.routes       |   |
    |  | config.ts        |   | session.svc  |   | middleware        |   |
    |  +------------------+   +--------------+   +-------------------+   |
    |                                                                     |
    |  Level 4: Testing        Level 5: Quality                          |
    |  +------------------+   +--------------+                           |
    |  | auth.test.ts     |   | docs/auth.md |                           |
    |  | user.test.ts     |   | cleanup      |                           |
    |  | e2e.test.ts      |   |              |                           |
    |  +------------------+   +--------------+                           |
    +---------------------------------------------------------------------+
                              |
        Phase 3               v
    +-------------------------------------+
    |      TASK GRAPH GENERATION          |
    |  - Exclusive file ownership         |
    |  - Verification commands            |
    |  - Dependency chains                |
    |  -> task-graph.json                 |
    +-------------------------------------+
                              |
        Phase 4               v
    +-------------------------------------+
    |      VALIDATION                     |
    |  - No circular dependencies         |
    |  - No file ownership conflicts      |
    |  - All files have exactly one owner |
    +-------------------------------------+
```

**What exclusive file ownership means:** Each file can only be created or modified by one task per level. If `auth.service.ts` is assigned to TASK-005, no other task in Level 2 can touch it. This eliminates merge conflicts by design.

#### Using It

```
/zerg:design
```

ZERG reads the approved requirements and generates architecture:
```
Architecture Design:

COMPONENTS:
+-- auth/
|   +-- types.ts          (Level 1: TASK-001)
|   +-- auth.service.ts   (Level 2: TASK-004)
|   +-- auth.routes.ts    (Level 3: TASK-007)
+-- user/
|   +-- types.ts          (Level 1: TASK-002)
|   +-- user.service.ts   (Level 2: TASK-005)
|   +-- user.routes.ts    (Level 3: TASK-008)
+-- tests/
    +-- auth.test.ts      (Level 4: TASK-010)
    +-- user.test.ts      (Level 4: TASK-011)

KEY DECISIONS:
- Using JWT for session tokens (stateless, scales horizontally)
- Storing refresh tokens in database (allows revocation)
- Password hashing with bcrypt cost factor 12

Task graph validated: 12 tasks, 5 levels, no conflicts.
Ready for /zerg:rush
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--help` | boolean | false | Show help message |

---

### /zerg:init

#### What Is It?

The init command sets up ZERG for your project. Think of it as the foundation work before building a house - you need the infrastructure in place before construction can begin.

ZERG operates in one of two modes depending on what it finds. If you run it in an empty directory, it starts an interactive wizard to help you build a new project from scratch (Inception Mode). If you run it in an existing codebase, it analyzes what you have and configures ZERG to work with your stack (Discovery Mode).

#### Why Use It?

Without initialization, ZERG has no idea what your project looks like. It does not know which programming languages you use, what frameworks are involved, or how to run your build and test commands. The init command discovers all of this and creates configuration files so every other ZERG command works correctly.

It also sets up security rules specific to your stack. If you are writing Python, you get Python security rules. If you are writing JavaScript, you get JavaScript rules. This means Claude Code automatically follows secure coding practices relevant to your actual codebase.

#### How It Works

```
+---------------------------------------------------------------------+
|                         /zerg:init                                  |
+---------------------------------------------------------------------+
                              |
                              v
                    +-----------------+
                    | Check directory |
                    +-----------------+
                              |
              +---------------+---------------+
              v                               v
     +----------------+              +----------------+
     | Empty: Wizard  |              | Existing: Scan |
     | - What to build|              | - Find files   |
     | - Tech stack   |              | - Detect lang  |
     | - Git init     |              | - Find infra   |
     +----------------+              +----------------+
              |                               |
              +---------------+---------------+
                              v
              +-------------------------------+
              |      Generate Files           |
              |  - .zerg/config.yaml          |
              |  - .devcontainer/             |
              |  - .gsd/PROJECT.md            |
              |  - .claude/rules/security/    |
              +-------------------------------+
```

**What the files mean:**
- `.zerg/config.yaml` - Main configuration: worker counts, timeouts, quality gates
- `.devcontainer/` - Docker configuration for isolated worker execution
- `.gsd/PROJECT.md` - High-level project description for ZERG to reference
- `.claude/rules/security/` - Language-specific security rules that Claude Code auto-loads

#### Using It

**New project (empty directory):**
```
mkdir my-api && cd my-api
zerg init
```

ZERG asks questions about what you want to build:
```
ZERG: What kind of project are you creating?
YOU:  A REST API for managing inventory

ZERG: Which languages/frameworks?
YOU:  Python with FastAPI

ZERG: Any specific infrastructure needs?
YOU:  PostgreSQL database, Redis for caching
```

**Existing project:**
```
cd my-existing-project
zerg init
```

ZERG scans and reports:
```
Detected:
  Languages: Python 3.11, TypeScript 5.0
  Frameworks: FastAPI, React
  Infrastructure: Docker, PostgreSQL
  Build: pyproject.toml, package.json

Created:
  .zerg/config.yaml
  .gsd/PROJECT.md
  .gsd/INFRASTRUCTURE.md
  .claude/rules/security/languages/python/CLAUDE.md
  .claude/rules/security/languages/javascript/CLAUDE.md
```

**With options:**
```
# Skip security rules (faster, less secure)
zerg init --no-security-rules

# Set strict security and 3 workers
zerg init --workers 3 --security strict

# Build Docker container after init
zerg init --with-containers
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--workers` | integer | 5 | Set default worker count |
| `--security` | string | "" | Security level (e.g., `strict`) |
| `--no-security-rules` | boolean | false | Skip fetching security rules |
| `--with-containers` | boolean | false | Build devcontainer after init |

---

### /zerg:plan

#### What Is It?

The plan command captures detailed requirements for a specific feature. While brainstorm helps you figure out what to build, plan documents exactly how it should work. It produces a requirements document that serves as the contract for the implementation.

Think of it as writing a detailed spec before coding. The plan command asks questions about your feature until it has enough information to write unambiguous requirements that any developer (or AI) could implement correctly.

#### Why Use It?

Vague requirements produce vague code. When you tell an AI "build user authentication," you might get basic username/password, or you might get a full OAuth implementation. The plan command eliminates ambiguity by forcing you to specify exactly what you want.

The output (requirements.md) becomes the single source of truth for the design and implementation phases. Workers read this document and implement exactly what it says. If requirements are clear, implementation is straightforward.

#### How It Works

```
+---------------------------------------------------------------------+
|                         /zerg:plan                                  |
+---------------------------------------------------------------------+
                              |
        Phase 1               v
    +-------------------------------------+
    |        CONTEXT GATHERING            |
    |  - Read PROJECT.md                  |
    |  - Read INFRASTRUCTURE.md           |
    |  - Search codebase for patterns     |
    +-------------------------------------+
                              |
        Phase 2               v
    +-------------------------------------+
    |     REQUIREMENTS ELICITATION        |
    |  - Problem space questions          |
    |  - Functional requirements          |
    |  - Non-functional requirements      |
    |  - Scope boundaries                 |
    |  - Acceptance criteria              |
    +-------------------------------------+
                              |
        Phase 3               v
    +-------------------------------------+
    |      GENERATE requirements.md       |
    |  -> .gsd/specs/{feature}/           |
    +-------------------------------------+
                              |
        Phase 4               v
    +-------------------------------------+
    |      APPROVAL CHECKPOINT            |
    |  Status: DRAFT -> REVIEW -> APPROVED|
    +-------------------------------------+
                              |
                              v
              User says "APPROVED"
              -> Ready for /zerg:design
```

**What the status markers mean:**
- `DRAFT` - Requirements captured but not yet reviewed
- `REVIEW` - Under review, may have questions
- `APPROVED` - Ready for design phase
- `REJECTED` - Needs revision

#### Using It

**Plan a feature:**
```
/zerg:plan user-authentication
```

ZERG asks targeted questions:
```
ZERG: Let me understand the scope. What authentication methods should
      this feature support?
YOU:  Email/password and OAuth with Google.

ZERG: For the email/password flow:
      - Should users verify their email before accessing the app?
      - What are the password complexity requirements?
YOU:  Yes, email verification required. Password must be 12+ chars
      with at least one number and symbol.

ZERG: For OAuth:
      - Which Google scopes do you need (email, profile, etc)?
      - What happens if a Google user already has an email/password account?
YOU:  Just email and profile. Link accounts if email matches.

ZERG: Non-functional requirements:
      - What's the expected login volume (logins per second)?
      - Session duration? Token refresh policy?
YOU:  ~10 logins/sec peak. 1-hour sessions, refresh if active.
```

ZERG generates `requirements.md` and asks for approval:
```
Requirements generated. Key points:

FUNCTIONAL:
- FR-1: Email/password authentication with verification
- FR-2: Google OAuth with account linking
- FR-3: Session management with 1-hour expiry

NON-FUNCTIONAL:
- NFR-1: Handle 10 logins/second
- NFR-2: Sub-200ms login latency

Please review and reply APPROVED or REJECTED with feedback.
```

**Structured Socratic mode:**
```
/zerg:plan user-authentication --socratic --rounds 5
```

Five structured rounds of one question at a time, going deeper into problem space, solution space, and implementation details.

**Flags:**

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--socratic` | `-s` | boolean | false | Use structured discovery mode |
| `--rounds` | | integer | 3 | Number of Socratic rounds (max: 5) |
| `--from-issue` | | string | "" | Import requirements from GitHub issue URL |

---

### /zerg:rush

#### What Is It?

The rush command is ZERG's execution engine. It takes your approved design and turns it into action by launching multiple Claude Code instances that work on different parts of your feature simultaneously.

Think of it like a construction site manager: you have the blueprints (from /zerg:design), and now rush assigns workers to different rooms so they can all build at once instead of waiting for one worker to finish each room.

#### Why Use It?

Without parallelization, building a feature with 20 files takes a single Claude Code instance hours of sequential work. Rush spawns multiple workers, each handling their assigned files, reducing build time by 3-5x.

The command also handles the complexity you would otherwise manage manually: coordinating workers, running quality checks between levels, retrying failed tasks, and merging changes back together. You launch rush and watch progress instead of babysitting individual tasks.

#### How It Works

```
+---------------------------------------------------------------------+
|                        ORCHESTRATOR                                 |
|  Reads task-graph.json, assigns tasks to workers by level           |
+---------------------------------------------------------------------+
                              |
                              | Level 1 Start
         +--------------------+--------------------+
         v                    v                    v
    +---------+          +---------+          +---------+
    | Worker 0|          | Worker 1|          | Worker 2|
    | TASK-001|          | TASK-002|          | TASK-003|
    | types.ts|          | schema.ts|         | config.ts|
    +---------+          +---------+          +---------+
         |                    |                    |
         v                    v                    v
    +-----------------------------------------------------+
    |                   LEVEL 1 COMPLETE                  |
    |  Merge branches, run quality gates (lint, test)     |
    +-----------------------------------------------------+
                              |
                              | Level 2 Start
         +--------------------+--------------------+
         v                    v                    v
    +---------+          +---------+          +---------+
    | Worker 0|          | Worker 1|          | Worker 2|
    | TASK-004|          | TASK-005|          | TASK-006|
    | auth.svc|          | user.svc|          | session |
    +---------+          +---------+          +---------+
         |                    |                    |
         v                    v                    v
    +-----------------------------------------------------+
    |                   LEVEL 2 COMPLETE                  |
    |  ... and so on through all levels ...               |
    +-----------------------------------------------------+
```

**What "level by level" means:** All workers must complete Level 1 before any worker starts Level 2. This ensures that when workers build services (Level 2), the types they depend on (Level 1) already exist.

**What quality gates mean:** Between levels, rush automatically runs lint, type checking, and tests. If anything fails, execution pauses so you can fix issues before they propagate.

#### Using It

**Basic launch with 5 workers:**
```
/zerg:rush --workers=5
```

Output shows real-time progress:
```
Rush started: user-authentication
Workers: 5 | Mode: task

Level 1 (Foundation):
  [Worker 0] TASK-001 types.ts .......... DONE
  [Worker 1] TASK-002 schema.ts ......... DONE
  [Worker 2] TASK-003 config.ts ......... DONE

Quality gates: lint OK | typecheck OK | tests OK

Level 2 (Core):
  [Worker 0] TASK-004 auth.service ...... RUNNING
  [Worker 1] TASK-005 user.service ...... RUNNING
  [Worker 2] TASK-006 session.service ... RUNNING
```

**Resume after interruption:**
```
/zerg:rush --resume
```

ZERG loads state from the checkpoint file and continues where it left off:
```
Resuming user-authentication from Level 2
Completed: 3/12 tasks
Remaining: 9 tasks across 4 levels
```

**Preview execution plan:**
```
/zerg:rush --dry-run
```

Shows what would happen without starting:
```
Dry run: user-authentication

Level 1: 3 tasks -> 3 workers (1 task each)
Level 2: 3 tasks -> 3 workers (1 task each)
Level 3: 3 tasks -> 3 workers (1 task each)
Level 4: 2 tasks -> 2 workers
Level 5: 1 task  -> 1 worker

Estimated time: 45 minutes with 5 workers
Estimated cost: ~$2.50 API credits
```

**Container mode for full isolation:**
```
/zerg:rush --mode container
```

Each worker runs in its own Docker container with a separate git worktree. Complete isolation means no chance of workers interfering with each other.

**Compare worker configurations:**
```
/zerg:rush --dry-run --what-if
```

Shows side-by-side comparison of different worker counts and execution modes to help you choose the optimal configuration.

**Assess risk before launching:**
```
/zerg:rush --dry-run --risk
```

Displays a risk assessment for the task graph, highlighting potential issues like large files, complex dependencies, or tasks that historically fail.

**Flags:**

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--workers` | `-w` | integer | 5 | Number of parallel workers (max: 10) |
| `--feature` | `-f` | string | auto | Feature name |
| `--level` | `-l` | integer | 1 | Start from specific level |
| `--task-graph` | `-g` | string | auto | Path to task-graph.json |
| `--mode` | `-m` | string | task | Execution mode: `subprocess`, `container`, `task` |
| `--dry-run` | | boolean | false | Show execution plan |
| `--resume` | | boolean | false | Continue from previous run |
| `--timeout` | | integer | 3600 | Max execution time in seconds |
| `--check-gates` | | boolean | false | Pre-run quality gates during dry-run |
| `--what-if` | | boolean | false | Compare different worker counts and modes |
| `--risk` | | boolean | false | Show risk assessment for task graph |
| `--skip-tests` | | boolean | false | Skip test gates (lint-only mode) |

---

## Monitoring and Control

These commands help you observe what is happening during execution and take action when things go wrong.

---

### /zerg:cleanup

#### What Is It?

The cleanup command removes ZERG artifacts after a feature is complete or when you want to start fresh. It cleans up worktrees, branches, containers, and state files while preserving your actual code and spec documents.

Think of it as clearing the construction site after building is done. Remove the scaffolding, clean up debris, but leave the finished building intact.

#### Why Use It?

ZERG creates many temporary artifacts: git worktrees for each worker, state files for checkpointing, log files for debugging, and Docker containers for isolation. After a feature is complete, these just take up space.

Cleanup also helps when something goes wrong. If state becomes corrupt or you want to restart fresh, cleanup resets everything to a clean state.

#### How It Works

```
+---------------------------------------------------------------------+
|                         /zerg:cleanup                               |
+---------------------------------------------------------------------+
                              |
                              v
    +-----------------------------------------------------+
    |                  PRESERVED (NOT DELETED)            |
    |  - Source code on main branch                       |
    |  - Merged commits                                   |
    |  - Spec files (.gsd/specs/)                         |
    |  - Task history (archived first)                    |
    +-----------------------------------------------------+
                              |
                              v
    +-----------------------------------------------------+
    |                     REMOVED                         |
    |  - Worktrees (.zerg/worktrees/)                     |
    |  - State files (.zerg/state/)                       |
    |  - Log files (.zerg/logs/) [unless --keep-logs]     |
    |  - Git branches [unless --keep-branches]            |
    |  - Docker containers                                |
    +-----------------------------------------------------+
                              |
                              v
    +-----------------------------------------------------+
    |                 ARCHIVE TASK HISTORY                |
    |  -> .zerg/archive/{feature}/tasks-{timestamp}.json  |
    +-----------------------------------------------------+
```

**Why specs are preserved:** The spec files in `.gsd/specs/` serve as documentation of what was built and why. They are valuable for future reference and should not be deleted.

#### Using It

**Clean specific feature:**
```
zerg cleanup --feature user-auth
```

Output:
```
Cleaning up user-auth:

Archived task history to .zerg/archive/user-auth/tasks-20260204.json

Removing:
  [x] Worktrees: 5 removed
  [x] State files: 3 removed
  [x] Log files: 12 removed
  [x] Git branches: 6 removed
  [x] Docker containers: 5 removed

Preserved:
  [v] Source code on main
  [v] Spec files in .gsd/specs/user-auth/
  [v] 23 commits in git history

Delete task history from Task system? [y/N]: n
Task history preserved.

Cleanup complete.
```

**Preview cleanup plan:**
```
zerg cleanup --all --dry-run
```

Shows what would be deleted without actually deleting.

**Keep logs for debugging:**
```
zerg cleanup --feature user-auth --keep-logs
```

**Keep branches for inspection:**
```
zerg cleanup --feature user-auth --keep-branches
```

**Flags:**

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--feature` | `-f` | string | "" | Feature to clean (required unless `--all`) |
| `--all` | | boolean | false | Clean all ZERG features |
| `--keep-logs` | | boolean | false | Preserve log files |
| `--keep-branches` | | boolean | false | Preserve git branches |
| `--dry-run` | | boolean | false | Show cleanup plan |

---

### /zerg:logs

#### What Is It?

The logs command gives you access to the detailed output from workers. While status shows high-level progress, logs show exactly what each worker said and did. This is essential for debugging when something goes wrong.

Think of it as reading a contractor's detailed work journal instead of just knowing they finished. If a task failed, logs tell you why.

#### Why Use It?

When a task fails, you need to understand what happened. Did the verification command fail? Was there a compilation error? Did the worker misunderstand the requirements? Logs contain the full context including Claude's reasoning, command output, and error messages.

Logs also help with optimization. If a task took much longer than expected, logs reveal where time was spent.

#### How It Works

```
+---------------------------------------------------------------------+
|                          /zerg:logs                                 |
+---------------------------------------------------------------------+
                              |
         +--------------------+--------------------+
         v                    v                    v
    +------------+      +------------+      +------------+
    |  Worker 0  |      |  Worker 1  |      |  Worker 2  |
    | worker.jsonl|     | worker.jsonl|     | worker.jsonl|
    +------------+      +------------+      +------------+
         |                    |                    |
         +--------------------+--------------------+
                              | --aggregate
                              v
    +-----------------------------------------------------+
    |            MERGED TIMELINE (by timestamp)           |
    |                                                     |
    |  10:00:01 [W0] Task TASK-001 started               |
    |  10:00:02 [W1] Task TASK-002 started               |
    |  10:00:03 [W2] Task TASK-003 started               |
    |  10:02:34 [W0] Task TASK-001 verification passed   |
    |  10:02:35 [W0] Task TASK-001 committed             |
    |  ...                                                |
    +-----------------------------------------------------+

    Task Artifacts (.zerg/logs/tasks/TASK-001/):
    +-- execution.jsonl      # Step-by-step execution log
    +-- claude_output.txt    # Full Claude Code output
    +-- verification_output.txt  # Test/lint output
    +-- git_diff.patch       # Changes made
```

**What artifacts mean:** Each task saves detailed artifacts including Claude's full output, verification results, and the git diff of changes. This lets you reconstruct exactly what happened after the fact.

#### Using It

**Recent logs from all workers:**
```
zerg logs
```

Output:
```
[10:15:32] [W0] TASK-004 started: auth.service.ts
[10:15:33] [W1] TASK-005 started: user.service.ts
[10:18:45] [W0] TASK-004 verification started
[10:18:47] [W0] TASK-004 verification PASSED
[10:18:48] [W0] TASK-004 committed: "feat(auth): implement auth service"
[10:19:01] [W1] TASK-005 verification started
[10:19:15] [W1] TASK-005 verification FAILED: type error
```

**Logs from specific worker:**
```
zerg logs 1
```

**Filter by log level:**
```
zerg logs --level error
```

Only shows errors:
```
[10:19:15] [W1] ERROR: TASK-005 verification failed
           Type 'string' is not assignable to type 'User'
           at src/user/user.service.ts:45:12
```

**Show task artifacts:**
```
zerg logs --artifacts TASK-005
```

Output shows the saved files:
```
Task TASK-005 artifacts:

=== execution.jsonl ===
{"phase":"claim","timestamp":"10:15:33"}
{"phase":"execute","timestamp":"10:15:34","step":"reading_spec"}
{"phase":"execute","timestamp":"10:17:20","step":"writing_code"}
{"phase":"verify","timestamp":"10:19:01","result":"failed"}

=== verification_output.txt ===
src/user/user.service.ts:45:12 - error TS2322
Type 'string' is not assignable to type 'User'

=== git_diff.patch ===
+++ b/src/user/user.service.ts
@@ -42,6 +42,10 @@
+  async getUser(id: string): User {  // Bug: should return Promise<User>
+    return this.db.query('SELECT * FROM users WHERE id = ?', [id]);
+  }
```

**Aggregate all logs by timestamp:**
```
zerg logs --aggregate
```

Merges all worker logs into a single chronological timeline.

**Flags:**

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `WORKER_ID` | | integer | all | Filter to specific worker (positional) |
| `--feature` | `-f` | string | auto | Feature name |
| `--tail` | `-n` | integer | 100 | Number of lines to show |
| `--follow` | | boolean | false | Stream logs continuously |
| `--level` | `-l` | string | all | Filter: `debug`, `info`, `warn`, `error` |
| `--aggregate` | | boolean | false | Merge all worker logs |
| `--task` | | string | "" | Filter to specific task ID |
| `--artifacts` | | string | "" | Show artifact contents |

---

### /zerg:merge

#### What Is It?

The merge command combines completed work from multiple workers into a single branch. Each worker creates code on its own branch, and merge brings those branches together after a level completes.

Think of it as combining work from multiple contractors into the final building. Each contractor worked on their own section, and now we join them together and run inspections (quality gates).

#### Why Use It?

Normally, rush handles merging automatically after each level. But sometimes you need manual control - maybe automatic merge failed due to a conflict, or you want to skip quality gates temporarily, or you are debugging a merge issue.

Merge gives you direct control over the level merge process when automatic handling is not enough.

#### How It Works

```
+---------------------------------------------------------------------+
|                         /zerg:merge                                 |
+---------------------------------------------------------------------+
                              |
                              v
    +-----------------------------------------------------+
    |         CHECK LEVEL COMPLETION                      |
    |  All tasks at level must be DONE                    |
    +-----------------------------------------------------+
                              |
                              v
    +-----------------------------------------------------+
    |         COLLECT WORKER BRANCHES                     |
    |  zerg/{feature}/worker-0                            |
    |  zerg/{feature}/worker-1                            |
    |  zerg/{feature}/worker-2                            |
    +-----------------------------------------------------+
                              |
                              v
    +-----------------------------------------------------+
    |         CREATE STAGING BRANCH                       |
    |  zerg/{feature}/staging-level-2                     

…(truncated)