tools-only ZERG Command Guide
Complete documentation with explanations, diagrams, and examples. For quick lookup, see Quick Reference.
This guide assumes you know basic programming and git (commit, branch, push) but are new to AI coding assistants and distributed task execution. Every command is explained with:
- What Is It? - The concept in plain language
- Why Use It? - The problem it solves
- How It Works - Visual diagram of the flow
- Using It - Command examples with expected output
Table of Contents
Core Workflow
The core workflow commands are the backbone of ZERG. They 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: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 │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ Check directory │
└─────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌────────────────┐ ┌────────────────┐
│ Empty: Wizard │ │ Existing: Scan │
│ - What to build│ │ - Find files │
│ - Tech stack │ │ - Detect lang │
│ - Git init │ │ - Find infra │
└────────────────┘ └────────────────┘
│ │
└───────────────┬───────────────┘
▼
┌───────────────────────────────┐
│ 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
/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 ▼
┌─────────────────────────────────────┐
│ RESEARCH │
│ - Search competitors │
│ - Find market gaps │
│ - Identify trends │
└─────────────────────────────────────┘
│
Phase 2 ▼
┌─────────────────────────────────────┐
│ SOCRATIC DISCOVERY │
│ Round 1: Problem Space │
│ Round 2: Solution Space │
│ Round 3: Implementation Space │
└─────────────────────────────────────┘
│
Phase 2.5-2.7 ▼
┌─────────────────────────────────────┐
│ VALIDATION │
│ - Trade-off exploration │
│ - Design checkpoints │
│ - YAGNI gate (filter extras) │
└─────────────────────────────────────┘
│
Phase 3 ▼
┌─────────────────────────────────────┐
│ ISSUE GENERATION │
│ - Create GitHub issues │
│ - Add acceptance criteria │
│ - Apply priority labels │
└─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 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
/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 ▼
┌─────────────────────────────────────┐
│ CONTEXT GATHERING │
│ - Read PROJECT.md │
│ - Read INFRASTRUCTURE.md │
│ - Search codebase for patterns │
└─────────────────────────────────────┘
│
Phase 2 ▼
┌─────────────────────────────────────┐
│ REQUIREMENTS ELICITATION │
│ - Problem space questions │
│ - Functional requirements │
│ - Non-functional requirements │
│ - Scope boundaries │
│ - Acceptance criteria │
└─────────────────────────────────────┘
│
Phase 3 ▼
┌─────────────────────────────────────┐
│ GENERATE requirements.md │
│ → .gsd/specs/{feature}/ │
└─────────────────────────────────────┘
│
Phase 4 ▼
┌─────────────────────────────────────┐
│ APPROVAL CHECKPOINT │
│ Status: DRAFT → REVIEW → APPROVED │
└─────────────────────────────────────┘
│
▼
User says "APPROVED"
→ Ready for /zerg:design
What the status markers mean:
DRAFT- Requirements captured but not yet reviewedREVIEW- Under review, may have questionsAPPROVED- Ready for design phaseREJECTED- 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.
Import from GitHub issue:
/zerg:plan --from-issue https://github.com/org/repo/issues/42
Reads the issue title, body, labels, and comments to pre-populate requirements. You still review and approve before proceeding.
/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:
- Breaking work into tasks with clear boundaries
- Assigning exclusive file ownership (no conflicts possible)
- 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 ▼
┌─────────────────────────────────────┐
│ ARCHITECTURE DESIGN │
│ - Component analysis │
│ - Data flow mapping │
│ - Interface definitions │
│ - Key decisions documented │
└─────────────────────────────────────┘
│
Phase 2 ▼
┌─────────────────────────────────────────────────────────────────┐
│ 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 ▼
┌─────────────────────────────────────┐
│ TASK GRAPH GENERATION │
│ - Exclusive file ownership │
│ - Verification commands │
│ - Dependency chains │
│ → task-graph.json │
└─────────────────────────────────────┘
│
Phase 4 ▼
┌─────────────────────────────────────┐
│ 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
The task-graph.json includes everything workers need:
{
"tasks": [
{
"id": "TASK-001",
"level": 1,
"title": "Create auth types",
"files": {
"create": ["src/auth/types.ts"],
"modify": [],
"read": ["src/shared/types.ts"]
},
"verification": "npx tsc --noEmit src/auth/types.ts",
"dependencies": []
}
]
}
/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
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Worker 0│ │ Worker 1│ │ Worker 2│
│ TASK-001│ │ TASK-002│ │ TASK-003│
│ types.ts│ │ schema.ts│ │ config.ts│
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────┐
│ LEVEL 1 COMPLETE │
│ Merge branches, run quality gates (lint, test) │
└─────────────────────────────────────────────────────┘
│
│ Level 2 Start
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Worker 0│ │ Worker 1│ │ Worker 2│
│ TASK-004│ │ TASK-005│ │ TASK-006│
│ auth.svc│ │ user.svc│ │ session │
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────┐
│ 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 before launching:
/zerg:rush --dry-run --what-if
Shows side-by-side comparison of different worker counts and modes so you can pick the optimal setup.
Assess risk in your task graph:
/zerg:rush --dry-run --risk
Highlights risky tasks: large files, complex dependencies, or historically problematic patterns.
Pre-validate quality gates during dry-run:
/zerg:rush --dry-run --check-gates
Runs lint, type check, and test gates against the current codebase before any workers start.
Skip test gates for faster iteration:
/zerg:rush --skip-tests
Runs only lint gates between levels, deferring test execution to the final level. Useful during rapid prototyping.
Monitoring and Control
These commands help you observe what is happening during execution and take action when things go wrong.
/zerg:status
What Is It?
The status command shows you exactly what is happening across all workers and tasks. It is your dashboard into the parallel execution, answering questions like: How many tasks are done? Which workers are active? Are there any failures?
Think of it as a project management dashboard that updates in real-time. Instead of asking each contractor individually what they are working on, you look at a single screen that shows everyone's progress.
Why Use It?
When five workers are running simultaneously, you need visibility. Without status, you would have to read individual log files to understand what is happening. Status aggregates all that information into a single, readable view.
It also helps you catch problems early. If a worker has been stuck on the same task for 10 minutes, status shows that so you can investigate before wasting more time.
How It Works
┌─────────────────────────────────────────────────────────────────────┐
│ /zerg:status │
└─────────────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Task │ │ State │ │ Git │
│ System │ │ JSON │ │ Branches│
│(primary)│ │(backup) │ │ Commits │
└─────────┘ └─────────┘ └─────────┘
│ │ │
└────────────────────┼────────────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ STATUS VIEW │
│ │
│ FEATURE: user-authentication │
│ PROGRESS: [=========> ] 45% (5/12 tasks) │
│ │
│ LEVEL 2 OF 5 │
│ ┌────────┬────────┬───────────┬──────────┐ │
│ │ Worker │ Status │ Task │ Duration │ │
│ ├────────┼────────┼───────────┼──────────┤ │
│ │ 0 │ RUNNING│ TASK-004 │ 3:45 │ │
│ │ 1 │ RUNNING│ TASK-005 │ 2:30 │ │
│ │ 2 │ DONE │ TASK-006 │ 4:12 │ │
│ └────────┴────────┴───────────┴──────────┘ │
│ │
│ FAILED: 0 | BLOCKED: 0 | REMAINING: 7 │
└─────────────────────────────────────────────────────┘
Data sources explained:
- Task System (primary) - The Claude Code Task system tracks all work across sessions
- State JSON (backup) - Local file with checkpoint data
- Git Branches - Each worker commits to its own branch, showing actual code progress
If Task System and State JSON disagree, status flags the mismatch so you can investigate.
Using It
Show overall status:
/zerg:status
Output:
FEATURE: user-authentication
PROGRESS: ████████░░░░░░░░░░░░ 42% (5/12 tasks)
CURRENT LEVEL: 2 (Core)
┌────────┬──────────┬───────────┬──────────┬─────────┐
│ Worker │ Status │ Task │ Duration │ Files │
├────────┼──────────┼───────────┼──────────┼─────────┤
│ 0 │ RUNNING │ TASK-004 │ 3:45 │ 2 │
│ 1 │ RUNNING │ TASK-005 │ 2:30 │ 1 │
│ 2 │ IDLE │ - │ - │ - │
│ 3 │ RUNNING │ TASK-006 │ 4:12 │ 2 │
│ 4 │ RUNNING │ TASK-007 │ 1:15 │ 1 │
└────────┴──────────┴───────────┴──────────┴─────────┘
COMPLETED LEVELS: 1 (Foundation)
REMAINING: 7 tasks across 3 levels
ESTIMATED TIME: 25 minutes
Watch mode (auto-refresh every 5 seconds):
/zerg:status --watch --interval 5
Show all tasks with details:
/zerg:status --tasks
Output includes task-level detail:
TASK-001 types.ts ✓ DONE Worker 0 2:34
TASK-002 schema.ts ✓ DONE Worker 1 1:58
TASK-003 config.ts ✓ DONE Worker 2 2:12
TASK-004 auth.service ○ RUNNING Worker 0 3:45
TASK-005 user.service ○ RUNNING Worker 1 2:30
TASK-006 session.service ✓ DONE Worker 3 4:12
TASK-007 routes ○ RUNNING Worker 4 1:15
...
Live TUI dashboard (CLI only):
zerg status --dashboard
Opens a terminal user interface with real-time updates, colored status indicators, and keyboard navigation.
/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 │
└─────────────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Worker 0 │ │ Worker 1 │ │ Worker 2 │
│ worker.jsonl│ │ worker.jsonl│ │ worker.jsonl│
└────────────┘ └────────────┘ └────────────┘
│ │ │
└────────────────────┼────────────────────┘
│ --aggregate
▼
┌─────────────────────────────────────────────────────┐
│ 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.
/zerg:stop
What Is It?
The stop command halts worker execution, either gracefully (with checkpoints) or forcefully (immediate termination). Use it when you need to pause work, fix an issue, or free up resources.
Think of it as telling contractors to stop for lunch (graceful) versus pulling the fire alarm (force). Graceful stop lets workers finish their current step and save progress. Force stop just terminates everything immediately.
Why Use It?
Sometimes you need to stop mid-execution. Maybe you spotted a problem in the design, need to step away, or want to adjust worker count. Stop allows you to pause without losing progress.
Graceful stop is important because it preserves work-in-progress. Workers commit their current state before stopping, so when you resume, they pick up exactly where they left off instead of restarting the task from scratch.
How It Works
┌─────────────────────────────────────────────────────────────────────┐
│ /zerg:stop │
└─────────────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ GRACEFUL STOP │ │ FORCE STOP │
│ (default) │ │ (--force) │
└─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Send checkpoint │ │ Kill processes │
│ signal │ │ immediately │
└─────────────────┘ └─────────────────┘
│ │
▼ │
┌─────────────────┐ │
│ Workers commit │ │
│ WIP changes │ │
└─────────────────┘ │
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Task marked │ │ Task marked │
│ PAUSED │ │ FORCE STOPPED │
└─────────────────┘ └─────────────────┘
│ │
└───────────────┬───────────────┘
▼
Resume with /zerg:rush --resume
What WIP commit means: Work-in-progress. The worker commits whatever code it has written so far, even if incomplete, so nothing is lost. The commit message notes the progress percentage.
Using It
Graceful stop (recommended):
zerg stop
Output:
Stopping workers gracefully...
Worker 0: Checkpointing TASK-004 (75% complete)...
Worker 1: Checkpointing TASK-005 (50% complete)...
Worker 2: Idle, stopping immediately
All workers stopped. State saved.
Resume with: zerg rush --resume
Stop specific worker:
zerg stop --worker 2
Only stops Worker 2; others continue:
Stopping Worker 2...
Worker 2: Checkpointing TASK-006 (90% complete)...
Worker 2 stopped. Other workers continuing.
Force stop (emergency):
zerg stop --force
Immediate termination:
Force stopping all workers...
Worker 0: Terminated (TASK-004 may have uncommitted changes)
Worker 1: Terminated (TASK-005 may have uncommitted changes)
Worker 2: Terminated
WARNING: Force stop may result in lost work.
Check task status before resuming.
/zerg:retry
What Is It?
The retry command re-executes failed tasks. When verification fails, a worker crashes, or something goes wrong, retry resets the task and assigns it to a new worker for another attempt.
Think of it as asking a contractor to redo their work after a failed inspection. The task goes back to "pending" status and gets picked up again.
Why Use It?
Failures happen. Maybe a worker hit a timeout, made an incorrect assumption, or encountered a transient error. Rather than manually investigating and fixing, retry often succeeds on the second attempt because:
- The error message from the first attempt provides context
- Transient issues (network, resources) may have resolved
- A different worker might approach the problem differently
Retry also tracks attempt counts to prevent infinite loops - by default, a task only gets 3 tries before you must investigate manually.
How It Works
┌─────────────────────────────────────────────────────────────────────┐
│ /zerg:retry │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ IDENTIFY FAILED TASKS │
│ - Check Task System for failed status │
│ - Read error logs and failure cause │
└─────────────────
…(truncated)