Frequently Asked Questions

Frequently Asked Questions

Common questions about ZERG, organized by topic. Each answer provides context, rationale, and cross-references to help you understand not just the "what" but the "why" behind ZERG's design.

Getting Started

What is ZERG and how is it different from regular Claude Code?

ZERG (Zero-Effort Rapid Growth) is a parallel execution system that coordinates multiple Claude Code instances to build features simultaneously. While regular Claude Code runs as a single agent working sequentially through tasks, ZERG fundamentally changes the development model by introducing parallelism, isolation, and spec-driven coordination.

The key insight behind ZERG is that most software features can be decomposed into independent work units that share no files within a given phase. By enforcing exclusive file ownership and organizing tasks into dependency levels, ZERG eliminates merge conflicts while maximizing parallel throughput. A single Claude Code instance might take 2 hours to implement a feature with 20 tasks; a ZERG swarm of 5 workers can complete the same work in 20-30 minutes by executing tasks concurrently within each level.

Unlike regular Claude Code, ZERG workers are stateless. They read specification documents fresh each time rather than relying on conversation history. This design enables crash recovery, restartability, and true parallelism since workers share no state. The orchestrator coordinates everything through the Claude Code Task system, which serves as the authoritative backbone for tracking progress across all workers.

This architecture also enables ZERG to auto-fetch security rules based on your detected tech stack and engineer context per worker to minimize token usage. Each worker receives only the instructions and context relevant to its assigned task, reducing per-worker token consumption by 30-50%.

For more details on system layers and module responsibilities, see Architecture.

How do I install ZERG?

ZERG installation involves two steps: installing the Python package and installing the slash commands into your project. The package provides the core orchestration logic, while the slash commands integrate ZERG into your Claude Code workflow.

# Clone and install the package
git clone https://github.com/rocklambros/zerg.git
cd zerg
pip install -e ".[dev]"
pre-commit install

# Install slash commands into your project
cd /path/to/your/project
zerg install

# Verify installation
zerg --help

The zerg install command copies command files into your project's .claude/commands/ directory, making them available as /zerg:* commands within Claude Code sessions. This approach keeps command definitions version-controlled with your project and allows customization.

Prerequisites include Python 3.12+, the Claude Code CLI (installed and authenticated), and Git. Docker is optional but required for container mode execution, which provides full worker isolation. If you plan to use container mode, ensure Docker is running and your user has permission to run containers.

After installation, run /zerg:init inside a Claude Code session to create the .zerg/ directory structure, generate the default configuration file, and fetch security rules for your detected tech stack.

For complete installation instructions and first-run guidance, see Home.

What's the minimum setup needed to start using ZERG?

The minimum setup to go from zero to a working ZERG swarm involves five commands, each representing a distinct phase of the ZERG workflow. Understanding what each phase does helps you use ZERG effectively.

1. zerg install (in terminal): Installs slash commands into your project, making /zerg:* commands available
2. /zerg:init (in Claude Code): Creates ZERG infrastructure (.zerg/ directory, config file, security rules)
3. /zerg:plan my-feature: Captures requirements through interactive dialogue, generating requirements.md
4. /zerg:design: Analyzes requirements to produce architecture documentation and a task graph with dependency levels
5. /zerg:rush --workers=3: Launches workers to execute the task graph in parallel

ZERG auto-detects your tech stack from files like pyproject.toml, package.json, and Dockerfile, then fetches appropriate security rules. It also creates a sensible default configuration file that works for most projects.

After your first successful run, subsequent features only require the plan-design-rush cycle. The infrastructure setup (init) is a one-time operation per project.

For a complete walkthrough of building your first feature, see Tutorial.

Execution Modes

What's the difference between task, subprocess, and container modes?

ZERG supports three worker execution modes, each with different isolation characteristics, resource requirements, and use cases. Understanding these trade-offs helps you choose the right mode for your situation.

Task mode is the default when running from Claude Code slash commands. Workers execute as Task sub-agents within your Claude Code session, sharing the same process space. This mode has minimal overhead and is ideal for typical development workflows. However, workers share filesystem access with the parent session.

Subprocess mode spawns separate Python processes for each worker. Each worker runs zerg.worker_main in its own process, providing memory isolation between workers. This mode requires no Docker but still shares the host filesystem. It's useful for development, testing, and environments where Docker isn't available.

Container mode provides maximum isolation by running each worker in its own Docker container. Workers have sandboxed filesystems, network isolation, and resource limits (CPU, memory). The host worktree is mounted into each container, and workers authenticate via OAuth (~/.claude mount) or API key (ANTHROPIC_API_KEY environment variable). This mode is recommended for production deployments and security-sensitive work.

If --mode is not specified, ZERG auto-detects the best option based on your environment: task mode inside Claude Code sessions, container mode if Docker is available with a devcontainer configuration, otherwise subprocess mode.

For container configuration options and security settings, see Configuration.

When should I use container mode?

Container mode is designed for scenarios where isolation, security, and reproducibility matter more than minimal overhead. Consider container mode when you need any of the following guarantees.

Full process and filesystem isolation: Each worker runs in its own container with an independent filesystem. One worker cannot read or write files outside its mounted worktree. If a worker somehow behaves unexpectedly, it cannot affect other workers or the host system beyond its designated scope.

Security boundaries: Containers run with dropped capabilities, read-only root filesystems, and optional network isolation. This defense-in-depth approach limits the blast radius of any potential security issue. Workers cannot install packages, modify system files, or access host resources outside explicit mounts.

Reproducible environments: Container images provide consistent execution environments regardless of host machine state. Workers always run in the same environment, eliminating "works on my machine" issues and ensuring predictable behavior across development, CI, and production.

Production deployments: When running ZERG in CI/CD pipelines or automated systems, container mode provides the isolation and resource limits necessary for safe multi-tenant execution.

Container mode does require Docker to be installed and running. Workers authenticate using either OAuth (by mounting ~/.claude read-only into containers) or API key (by passing ANTHROPIC_API_KEY as an environment variable). Both authentication methods are implemented in the launcher and work transparently.

For container resource limits and security configuration, see Configuration.

How many workers should I use?

Choosing the right worker count involves understanding your task graph's parallelization potential and balancing speedup against resource consumption. ZERG reports a "max parallelization" value during design—this is the maximum number of workers that can ever be simultaneously busy at any dependency level.

Understanding diminishing returns: If Level 2 of your task graph has only 3 parallelizable tasks, using 10 workers means 7 workers sit idle during that level. The speedup is limited by the narrowest level, not by how many workers you deploy. Check your task graph with /zerg:status before choosing worker count—it shows tasks per level.

Start conservative and scale up: For your first few features, start with 4 workers. Use /zerg:status during execution to see if workers are frequently waiting for dependencies. If all workers stay busy throughout, try adding more. If workers often idle, reduce the count to avoid wasted resources.

Resource considerations: Each worker consumes memory, API tokens, and (in container mode) CPU allocation. More workers mean faster completion but higher concurrent resource usage. In CI environments with limited resources, fewer workers with longer timeouts may be more reliable than many workers competing for resources.

For worker configuration options and resource tuning recommendations, see Configuration.

Git & Branching

How does ZERG handle git branches?

ZERG uses a structured branching model that isolates worker changes while enabling clean, conflict-free merges. Understanding this model helps you reason about where your code lives and how it flows toward integration.

The branching hierarchy consists of three levels:

1. Worker branches: Each worker operates on its own branch named zerg/{feature}/worker-{N}. Workers commit their changes here during task execution, isolated from each other.

2. Staging branch: zerg/{feature}/staging serves as the integration point. After all workers complete a level, the orchestrator merges all worker branches into staging, runs quality gates, and resolves any cross-level conflicts.

3. Main branch: The final destination. After all levels complete and pass quality gates, the staging branch merges to main (or your designated target branch).

Per-level merge flow:

1. Workers commit to their individual branches as they complete tasks
2. When all Level N tasks complete, the orchestrator merges all worker branches into staging
3. Quality gates (lint, typecheck, test) run on the merged staging code
4. If gates pass, staging becomes the base for Level N+1 worker branches
5. Workers rebase onto the new staging state before starting the next level

Workers never commit directly to main. The orchestrator controls all merges, ensuring quality gates run on the integrated code before it reaches main. This model prevents half-finished work from reaching main while allowing parallel development.

For details on the merge process and quality gates, see Architecture.

What are worktrees and why are they used?

Git worktrees are a feature that allows multiple working directories from the same repository, each checked out to a different branch. ZERG uses worktrees to give each worker its own isolated filesystem while sharing the underlying git repository.

.zerg-worktrees/{feature}-worker-0/  ->  branch: zerg/{feature}/worker-0
.zerg-worktrees/{feature}-worker-1/  ->  branch: zerg/{feature}/worker-1

Why worktrees instead of separate clones? Worktrees share the repository's object database, meaning git operations (commits, pushes, fetches) don't require network access to sync between workers. Creating a worktree is instant compared to cloning. And disk usage is minimal since object storage is shared.

Isolation benefits: Each worktree has its own working directory, staging area, and index. Worker 0 can stage and commit files without affecting Worker 1's state. Workers can edit the same file in different levels (since they work sequentially across levels, not concurrently on the same file).

Lifecycle: Worktrees are created automatically by /zerg:rush at the start of execution. Each worker operates entirely within its worktree directory. After execution completes, /zerg:cleanup removes worktrees to free disk space. The .zerg-worktrees/ directory is gitignored, so worktrees are never committed.

Debugging tip: If you need to inspect a worker's state during execution, you can cd into its worktree directory and use standard git commands (git status, git log, git diff) to see exactly what that worker has done.

For more on worktree management and the cleanup process, see Architecture.

How do I resolve merge conflicts?

ZERG's exclusive file ownership model is specifically designed to prevent merge conflicts. Each task in task-graph.json declares which files it creates and modifies, and the design phase ensures no two tasks at the same level touch the same file. This eliminates within-level conflicts entirely.

However, conflicts can still occur in two scenarios:

1. Cross-level modifications: Task A at Level 2 modifies config.py, and Task B at Level 3 also modifies config.py. These don't conflict during parallel execution (they're in different levels), but the merged result might have conflicts if both modified the same section.

2. External changes: You make manual edits on the staging branch while workers are executing, and those edits conflict with worker changes.

When ZERG detects a conflict, it pauses execution and reports the conflicting files and branches. To resolve:

1. Run /zerg:status to see which branches conflict and which files are affected
2. Check out the staging branch: git checkout zerg/{feature}/staging
3. Manually resolve conflicts using your preferred merge tool
4. Commit the resolution: git add . && git commit -m "Resolve merge conflicts"
5. Run /zerg:merge --continue to resume the merge process

Prevention is better than resolution: When designing tasks, ensure file ownership is truly exclusive. If two tasks need to modify the same file, either combine them into one task, split the file into separate files, or place the tasks in the same level so one depends on the other.

For merge process details and the --continue flag behavior, see Command-Reference.

Quality Gates

What quality gates run automatically?

Quality gates are validation commands that run after each level merge to verify the integrated code meets quality standards. They provide automated checkpoints that catch issues before they propagate to subsequent levels or reach the main branch.

Default gates (configurable in .zerg/config.yaml):

Gate execution and results:

• Pass (exit code 0): Continue to next level or final merge
• Fail (non-zero exit): If required: true, blocks the merge and pauses execution
• Timeout (exceeded time limit): Treated as failure
• Error (command couldn't run): Pauses for manual intervention

When a required gate fails, ZERG pauses and reports the failure. You can inspect the gate output, fix the issues, and resume with /zerg:merge --continue. Non-required gates warn but don't block—useful for advisory checks like coverage thresholds.

Why run gates after level merges? Individual workers verify their own tasks, but that doesn't guarantee the combined changes work together. A Level 2 task might pass verification in isolation but break a Level 1 feature when merged. Level gates catch these integration issues early, before building on a broken foundation.

For gate configuration options and adding custom gates, see Configuration.

How do I add custom quality gates?

Custom gates let you extend ZERG's validation beyond the defaults. You might add security scanning, coverage thresholds, documentation checks, or project-specific validations.

YAML configuration (simple shell commands):

quality_gates:
  - name: security-scan
    command: bandit -r src/ --severity medium
    required: false
    timeout: 300
  - name: coverage
    command: pytest --cov=src --cov-fail-under=80
    required: true
    timeout: 180
  - name: docs-check
    command: mkdocs build --strict
    required: false
    timeout: 120

Python plugins (complex logic, external integrations):

from zerg.plugins import QualityGatePlugin, GateContext
from zerg.types import GateRunResult
from zerg.constants import GateResult

class SonarQubeGate(QualityGatePlugin):
    @property
    def name(self) -> str:
        return "sonarqube"

    def run(self, ctx: GateContext) -> GateRunResult:
        # Call SonarQube API, parse results, decide pass/fail
        # Access ctx.feature, ctx.level, ctx.staging_branch
        return GateRunResult(
            gate_name=self.name,
            result=GateResult.PASS,
            command="sonar-scanner",
            exit_code=0,
            stdout="Quality gate passed"
        )

Python plugins are discovered via entry points (group: zerg.plugins). Add them to your pyproject.toml:

[project.entry-points."zerg.plugins"]
sonarqube-gate = "my_package.gates:SonarQubeGate"

Choosing between YAML and Python: Use YAML for simple shell commands that return pass/fail via exit codes. Use Python when you need to call APIs, parse complex output, maintain state, or implement conditional logic.

For the complete plugin API and hook event types, see Plugins.

Can I skip quality gates?

Yes, but understand the implications before doing so. Skipping gates trades confidence for speed—acceptable during development or debugging, but risky for production code.

Skipping all gates:

/zerg:merge --skip-gates

Skipping a specific gate:

/zerg:merge --skip-gate lint
/zerg:merge --skip-gate typecheck

Making gates non-blocking permanently: Set required: false in your configuration. Non-blocking gates run and report results but don't stop merges on failure. This is useful for advisory checks where you want visibility but not enforcement.

quality_gates:
  - name: coverage
    command: pytest --cov --cov-fail-under=80
    required: false  # Warn but don't block

When skipping makes sense:

• Debugging a stuck merge where you know the gate failure is unrelated
• Prototyping where you'll run gates manually later
• Temporary workaround for a flaky test while investigating root cause

When skipping is dangerous:

• Production deployments (skip gates, skip confidence)
• Team environments where others build on your merged code
• Any time you don't fully understand why the gate is failing

Remember: gates exist because integrated code can break in ways that individual task verification doesn't catch. Skipping gates means accepting that risk.

For gate configuration and the --skip-gate flag, see Command-Reference.

Containers

How does container authentication work?

Container workers need to authenticate with Claude's API to execute tasks. ZERG supports two authentication methods, automatically detecting which to use based on available credentials.

OAuth authentication: Your ~/.claude directory contains OAuth tokens from Claude Code authentication. ZERG mounts this directory read-only into containers at the same path, allowing workers to authenticate using your existing session. This is transparent—if you're authenticated in Claude Code, container workers inherit that authentication.

API key authentication: If ANTHROPIC_API_KEY is set in your environment, ZERG passes it into containers. This method works independently of OAuth and is useful for CI environments or when you want explicit API key control.

Detection priority: ZERG checks for OAuth credentials first (existence of ~/.claude with valid tokens), then falls back to API key if available. If neither is available, container startup fails with a clear authentication error.

Security considerations: OAuth tokens in ~/.claude are mounted read-only, preventing containers from modifying your credentials. API keys passed via environment variables are visible within the container but not logged by ZERG. For maximum security, use OAuth when possible since it doesn't expose raw credentials.

For environment variable handling and security configuration, see Configuration.

What resources do containers get?

Container resource allocation controls how much CPU, memory, and network access each worker receives. Default settings work for most projects, but you may need to adjust them for resource-intensive tasks or constrained environments.

Default resource limits (configurable in .zerg/config.yaml):

resources:
  container_memory_limit: "4g"   # 4 GB RAM per container
  container_cpu_limit: 2.0       # 2 CPU cores per container

Additional container settings:

• Read-only root filesystem: Containers cannot write to system directories, only to mounted volumes
• All capabilities dropped: No elevated privileges (CAP_SYS_ADMIN, etc.)
• Network isolation (optional): Containers can be isolated from the network except for API calls
• Port allocation: 10 ports per worker in the range 49152-65535 for any local services tasks might spawn

Why these defaults? 4GB memory accommodates Claude Code's working memory plus language server processes that might run during development tasks. 2 CPU cores allow parallel processing within a worker without starving other workers. These limits prevent any single worker from monopolizing host resources.

Adjusting for your needs:

• Memory-intensive tasks (large codebases, ML models): Increase container_memory_limit to "8g" or higher
• Resource-constrained hosts: Reduce limits and use fewer workers
• Fast I/O needs: Consider SSD-backed Docker storage drivers

Resource limits are enforced by Docker. If a container exceeds its memory limit, Docker kills it with an OOM (out-of-memory) error. ZERG detects this and marks the worker as failed, potentially retrying on another worker.

For all resource and container configuration options, see Configuration.

How do I troubleshoot container issues?

Container problems typically fall into a few categories: Docker daemon issues, authentication failures, resource exhaustion, or permission errors. Systematic diagnosis helps identify the root cause quickly.

Common issues and solutions:

Diagnostic commands:

# Check ZERG's view of the environment
/zerg:debug --env

# View logs for a specific worker
/zerg:logs --worker 0

# List all ZERG containers (running and stopped)
docker ps -a | grep zerg

# View container logs directly
docker logs zerg-worker-0

# Inspect container configuration
docker inspect zerg-worker-0

# Check resource usage
docker stats zerg-worker-0

Debugging workflow:

1. Run /zerg:debug --env to verify ZERG sees Docker and credentials correctly
2. Check if containers started: docker ps -a | grep zerg
3. If containers exist but failed, check logs: docker logs zerg-worker-N
4. Look for specific errors: authentication, OOM, permission denied
5. Fix the identified issue and retry with /zerg:rush --resume

When containers keep failing: Sometimes the issue is in the task itself, not the container. Compare container logs with the task's verification command. If the task verification is failing, the problem is the generated code, not containerization.

For comprehensive troubleshooting guides, see Troubleshooting.

Context & Tokens

How does context engineering reduce token usage?

Context engineering is ZERG's system for minimizing per-worker token consumption while preserving the information each task needs. When running 5-10 parallel workers, each one independently loads instructions and specifications—without optimization, this can consume 15,000-30,000 tokens per worker before any code is written.

ZERG addresses this through three coordinated subsystems:

1. Command Splitting: Large command files (>300 lines) are split into .core.md (30% essential instructions) and .details.md (70% reference material). Workers load only the core content by default, referencing details only when encountering situations that require them. This saves ~2,000-5,000 tokens per command file loaded.

2. Security Rule Filtering: Instead of loading all security rules (Python, JavaScript, Docker, OWASP core), ZERG analyzes each task's file extensions and loads only relevant rules. A task that only modifies .py files receives Python security rules and OWASP core, not Docker or JavaScript rules. This saves ~1,000-4,000 tokens per task depending on how many rule sets your project has.

3. Task-Scoped Context: Each task receives curated excerpts from requirements.md and design.md based on its title, description, and file list—not the entire specification documents. The context assembler identifies paragraphs that mention the task's files or topics and extracts them within a token budget. This saves ~2,000-5,000 tokens per task compared to loading full documents.

Combined impact:

At 10 workers, that's 150,000 tokens saved per execution cycle. The savings compound across multiple levels and features.

For configuration options and monitoring metrics, see Context-Engineering.

What's the token budget per task?

The token budget controls how much context each task receives from specification documents and upstream task outputs. The default budget of 4,000 tokens (~16,000 characters) covers most tasks well while leaving room for the worker's actual code generation work.

plugins:
  context_engineering:
    task_context_budget_tokens: 4000

What fits in 4,000 tokens:

• 2-4 paragraphs of specification excerpts (~2,000 tokens)
• Filtered security rules for the task's file types (~1,200 tokens)
• Dependency context from upstream tasks (~800 tokens)

Budget allocation and prioritization: The context assembler doesn't just truncate at 4,000 tokens—it prioritizes content:

1. Security rules (always included if relevant to file types)
2. Direct spec matches (paragraphs explicitly mentioning task files)
3. Topic-related content (semantic similarity to task description)
4. Dependency exports (interfaces and types from upstream tasks)

Lower-priority content is truncated first if the budget is exceeded.

When to adjust the budget:

• Increase to 5,000-6,000: Complex tasks with many dependencies, tasks touching multiple subsystems, tasks where workers consistently ask for clarification
• Decrease to 2,500-3,000: Simple tasks, maximum efficiency mode, when running many workers and minimizing total token usage is critical

Fallback behavior: If context engineering fails for any reason (missing files, parsing errors), workers fall back to loading full context if fallback_to_full: true. A worker with full context is better than a worker that fails to load instructions.

For tuning recommendations and troubleshooting low context rates, see Context-Engineering.

How is command splitting different from task context?

Command splitting and task context are complementary subsystems that optimize different aspects of worker token consumption. Understanding the distinction helps you monitor and troubleshoot each independently.

Command splitting addresses the fact that command files contain both essential workflow instructions and detailed reference material (examples, edge cases, configuration tables). Workers rarely need the full reference during normal execution, so splitting allows them to load just the essentials.

Task context addresses the fact that specification documents describe the entire feature, but each task only needs the parts relevant to its specific scope. A task implementing the JWT auth service doesn't need to know about the email notification requirements—it needs the authentication specification sections.

Both work together: A worker executing task AUTH-L2-001 loads:

1. worker.core.md (essential command instructions, not full worker.md)
2. Task AUTH-L2-001's scoped context (relevant spec excerpts, not full requirements.md + design.md)
3. Filtered security rules (Python rules only if task creates .py files)

Monitoring both: /zerg:status shows command split statistics and task context population rates in the CONTEXT BUDGET section.

For implementation details and configuration, see Context-Engineering.

Plugins

What plugin types are supported?

ZERG's plugin system supports three distinct plugin types, each serving a different role in the execution lifecycle. Understanding when to use each type helps you extend ZERG effectively.

Quality Gate plugins integrate with the merge process. After level merges, configured gates run sequentially. If a required gate fails, the merge blocks until you fix the issue and resume. Use gates when you need to enforce invariants on merged code.

Lifecycle Hook plugins respond to events throughout execution (task started, level completed, worker spawned, etc.) without blocking the workflow. Use hooks for observability, notifications, and side effects that shouldn't stop execution.

Launcher plugins control how workers execute. The built-in launchers (subprocess, container, task) cover most needs, but you might create custom launchers to run workers in Kubernetes pods, on remote servers via SSH, or in cloud VMs. Launchers are the most complex plugin type, requiring understanding of worker lifecycle and coordination protocols.

Plugins can be configured via YAML (shell commands) or implemented as Python classes (entry points). YAML is simpler for straightforward needs; Python provides full flexibility.

For the complete plugin API and entry point registration, see Plugins.

How do I create a custom plugin?

Custom plugins let you extend ZERG's behavior without modifying core code. The approach differs based on plugin complexity and type.

YAML-configured hooks (simplest—shell commands triggered by events):

plugins:
  hooks:
    - event: level_complete
      command: ./scripts/notify.sh "Level {level} done for {feature}"
      timeout: 60
    - event: task_completed
      command: echo "Task {task_id} completed" >> /tmp/zerg.log
      timeout: 10

Available event types: task_started, task_completed, level_complete, merge_complete, worker_spawned, quality_gate_run, rush_started, rush_finished. Commands support variable substitution for {level}, {feature}, {task_id}, {worker_id}.

Python Quality Gate plugins (full control over validation logic):

from zerg.plugins import QualityGatePlugin, GateContext
from zerg.types import GateRunResult
from zerg.constants import GateResult

class LicenseCheckGate(QualityGatePlugin):
    @property
    def name(self) -> str:
        return "license-check"

    def run(self, ctx: GateContext) -> GateRunResult:
        # ctx provides: feature, level, staging_branch, config
        # Implement your validation logic
        violations = self.scan_for_license_violations(ctx.staging_branch)

        if violations:
            return GateRunResult(
                gate_name=self.name,
                result=GateResult.FAIL,
                command="license-scanner",
                exit_code=1,
                stdout=f"Found {len(violations)} license violations",
                stderr="\n".join(violations)
            )

        return GateRunResult(
            gate_name=self.name,
            result=GateResult.PASS,
            command="license-scanner",
            exit_code=0,
            stdout="No license violations found"
        )

Registering Python plugins: Add entry points to your pyproject.toml:

[project.entry-points."zerg.plugins"]
license-check = "my_package.gates:LicenseCheckGate"
my-notifier = "my_package.hooks:SlackNotifierHook"

ZERG discovers plugins via importlib.metadata at startup. Your plugin class is instantiated and called at the appropriate lifecycle point.

For complete API documentation, available context fields, and example implementations, see Plugins.

Where are plugins configured?

All plugin configuration lives in .zerg/config.yaml under the plugins section. This centralizes plugin settings alongside other ZERG configuration, making it easy to see and modify plugin behavior.

plugins:
  enabled: true                    # Master switch for all plugins

  hooks:                           # YAML-configured lifecycle hooks
    - event: task_completed
      command: echo "Task done: {task_id}"
      timeout: 30
    - event: rush_finished
      command: ./scripts/notify-completion.sh {feature}
      timeout: 120

  quality_gates:                   # YAML-configured shell command gates
    - name: custom-security
      command: ./scripts/security-scan.sh
      required: true
      timeout: 300

  context_engineering:             # Built-in context optimization plugin
    enabled: true
    command_splitting: true
    security_rule_filtering: true
    task_context_budget_tokens: 4000
    fallback_to_full: true

Python plugins are discovered via entry points, not configured in YAML (they're registered in pyproject.toml). However, you can pass configuration to Python plugins through custom config sections:

plugins:
  sonarqube:                       # Custom section for SonarQubeGate plugin
    server_url: https://sonar.example.com
    project_key: my-project
    quality_gate_id: default

Your plugin reads this configuration via the GateContext.config dictionary.

Configuration precedence:

1. YAML-configured quality gates run in declaration order
2. Python quality gate plugins run after YAML gates
3. Lifecycle hooks fire immediately when events occur (non-blocking)
4. plugins.enabled: false disables all plugins system-wide

For the full configuration schema and all available options, see Configuration.

See Also

• Home - Project overview and quick start
• Tutorial - Step-by-step guide to building your first feature
• Command-Reference - All 26 commands with flags and examples
• Configuration - Complete config file reference
• Architecture - System design and module reference
• Context-Engineering - Token optimization deep dive
• Troubleshooting - Common issues and diagnostics
• Plugins - Plugin development guide
• Security - Security model and rule configuration