Guide

Getting started with CrewDefine and Zero

From empty machine to a Technical Due Diligence run — or author a configuration in CrewDefine and load it into Zero.

For First-time builders

Fast path — demo (recommended)

You do not need CrewDefine to try Zero. The Technical Due Diligence reference configuration ships inside Zero.

git clone https://github.com/lab-zee/Zero.git
cd Zero
cp .env.example .env
# Set GEMINI_API_KEY and/or OPENAI_API_KEY (OpenAI fallback strongly recommended)
./scripts/demo.sh

When healthy:

Frontend: http://localhost:3000
Backend: http://localhost:3001

Register / log in, create a workspace, open Chat. The top bar should read Technical Due Diligence. Supply architecture, dependency, security, or reliability evidence and watch the agent graph grow.

Configuration details: Technical Due Diligence.

Stop with Ctrl-C; docker compose down tears down containers.

What you’re building toward (full loop)

By the end of the longer path you’ll have:

CrewDefine installed and a crew directory on disk
Zero running locally (UI + API)
That crew loaded into Zero
A first chat where you can see agents run live

For deeper product detail later, see the CrewDefine and Zero deep dives. Public crews: /crews.

Prerequisites

Git, Docker Desktop (recommended for Zero)
An LLM key: Gemini (GEMINI_API_KEY) and/or OpenAI (OPENAI_API_KEY). Multi-agent runs burn free-tier RPM quickly — OpenAI as fallback is strongly recommended.
Optional: Node 20+, Python 3.11+ if you run without Docker or install CrewDefine from source

Clone both repos next to each other only if you want to author (paths below assume that):

git clone https://github.com/lab-zee/CrewDefine.git
git clone https://github.com/lab-zee/Zero.git

Part 1 — Author a crew (CrewDefine)

Skip this if you only want the demo. Maintained references under CrewDefine’s crews/ include technical-due-diligence, research-evidence-synthesis, and incident-analysis.

Install CrewDefine

cd CrewDefine
python3.11 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

You’ll need an Anthropic (or configured) API key for the interview LLM — see CrewDefine’s README / .env example.

Create a crew

crewdefine new

Follow the interview. You should end with a directory like:

crews/my-crew/
  crew.yaml
  agents/
    director.yaml
    synthesizer.yaml
    …
  tools/          # optional

Shortcut: use an existing example (e.g. dinner-planning) under CrewDefine/crews/ if you want to skip the interview on the first pass.

Validate

crewdefine validate ./crews/<name>

Fix anything it reports. Optional parity check against Zero’s validator:

ZERO_BACKEND=../Zero crewdefine validate ./crews/<name>

You’re done with Part 1 when validate exits clean and crew.yaml lists answer modes (and ideally output_composition).

Part 2 — Run Zero without a custom crew

If you already used ./scripts/demo.sh, skip ahead to Part 3 only when loading a different crew.

cd ../Zero
cp .env.example .env   # if needed
docker compose up --build

Leave AGENT_CONFIG_DIR unset — Zero uses the built-in Business Strategy roster.

Part 3 — Load your crew into Zero

Still in the Zero repo:

# Default example already in Zero:
./scripts/load-crew.sh --restart ./backend/crews/examples/technical-due-diligence

# Or a sibling CrewDefine package:
./scripts/load-crew.sh --restart ../CrewDefine/crews/<name>

What this does:

Copies agents/tools into backend/crews/active/
Writes .env overrides (AGENT_CONFIG_DIR, AGENT_PLUGINS_DIR, INJECT_COMMON_PROMPTS=false)
Restarts the backend so the new crew is live

Check it worked

Refresh http://localhost:3000
Top bar should show your crew’s display name (from crew.yaml)
Answer-mode labels should match what you defined
Ask something that needs specialists — watch the Agent run graph grow

Switch back to the default Business Strategy crew

./scripts/load-crew.sh --restart --default

Quick reference

# Demo (Technical Due Diligence)
cd Zero && ./scripts/demo.sh

# Author / iterate
cd CrewDefine && crewdefine new   # or edit YAML and re-validate

# Ship into a running Zero
cd Zero && ./scripts/load-crew.sh --restart ../CrewDefine/crews/<name>

Common failures

Symptom	Likely cause
`demo.sh` exits asking for keys	Fill `GEMINI_API_KEY` / `OPENAI_API_KEY` in `.env`
Can’t start Zero	Docker not running; check `docker compose logs backend`
Chat: missing API key	Set keys, recreate backend
Rate limit / fallback error	Free-tier Gemini RPM — wait ~1 min or rely on OpenAI fallback
Load script validation failed	Fix `crewdefine validate` errors first
UI still shows old crew	Hard-refresh; confirm `--restart` and backend healthy
Only Director runs	Crew may be clarifying on purpose — try a fuller prompt
Missing tools	Plugin not under `tools/` or not listed on an agent

Next steps

Reference configurations — technical due diligence, evidence synthesis, and incident analysis
Implementation services — fixed-scope domain configuration and integration
Working papers — architecture notes and preliminary experiments
CrewDefine deep dive · Zero deep dive
Bring your data into Zero

Canonical loader details also live in Zero’s repo: docs/CREW_HANDOFF.md.

← All guides · crewdefine , zero