evo docs — Engineering brain for AI-first teams

Quickstart

Download the binary

Single binary, zero dependencies. macOS (arm64/amd64), Linux (amd64/arm64), Windows.

# macOS Apple Silicon
curl -sL https://releases.evolabz.org/evo-darwin-arm64 -o evo
chmod +x evo
sudo mv evo /usr/local/bin/evo

Spawn the directive

evo outputs a directive template. Your AI reads this first.

evo spawn --project my-app > .evolution/directive.md

Integrate templates

evo outputs all project templates. Your AI fills them from codebase analysis.

evo integrate --project my-app
# AI reads templates, analyzes code, writes .evolution/ files

Validate

evo checks that the AI did its job — no unfilled placeholders, no leaked GENESIS comments.

evo validate --dir .
All checks passed (7 files, 0 errors)

Launch the dashboard

Visualize your project with Neural Mesh, Roadmap Flow, security, and more.

evo serve --port 8081
evo desktop # native app

Install

Pre-built Binaries

Platform	Binary
macOS CLI (arm64)	`build/evo-cli-mac-arm64`
macOS CLI (amd64)	`build/evo-cli-mac-amd64`
macOS Desktop (arm64)	`build/evo-macos-arm64-desktop-app.zip`
macOS Desktop (amd64)	`build/evo-macos-amd64-desktop-app.zip`

# Bypass Gatekeeper
xattr -cr Evo.app
xattr -d com.apple.quarantine evo-cli-mac-arm64

Build from Source

# CLI only
make build

# CLI + Svelte UI
make build-ui && make build

# Desktop app (macOS)
CGO_ENABLED=1 go build -tags "desktop,production" -o build/Evo.app ./cmd

# Multi-arch
make build-all

Core Commands

Command	Flags	Description
`evo spawn`	--project, --format (text\|json), --level (repo\|ws\|org), --team, --branches	Output directive.md template. Auto-detects context.
`evo integrate`	--project, --format, --branches, --override-branches	Output all templates. AI fills GENESIS sections from codebase.
`evo validate`	--dir (default "."), --format	Check for unfilled placeholders, leaked GENESIS comments, missing files.
`evo sync`	--dir, --commits (default 20)	Gather git context + .evolution/ files, output AI update instructions.
`evo sync-pulse`	--interval (default 15s)	Background daemon: auto git add/commit/pull/push for P2P mesh sync.
`evo tokens`	--dir	Estimate token budget for .evolution/ files (4 chars/token).
`evo onboarding`	(none)	Output 3-tier hierarchy architecture guide.
`evo version`	(none)	Print version (v0.1.0).

Org Commands

Top-level container. Workspaces one directory deep, repos one deeper.

Command	Flags	Description
`evo org init <name>`	positional name	Initialize org with .evolution/org.json.
`evo org discover`	--branches, --override-branches	Find workspace.json files, add to org.json. Auto-bootstraps workspaces.
`evo org discover-links`	(none)	AI orchestrator prompt to iteratively trace workspace links.
`evo org integrate`	--branches, --override-branches	Master cascading directive: auto-bootstrap entire org in one click.
`evo org coherence`	(none)	Full cascading validation: Org → Workspaces → Repos.
`evo org sync`	(none)	Sync context for all workspace repos, auto-skips synced.
`evo org sync-teams <github-org>`	positional	Sync GitHub organizational teams locally.
`evo org ai-sync`	(none)	Synchronize ORG and WS agent taxonomies.
`evo org analytics`	(none)	Collect org-wide analytics to .evolution/meta/analytics.json.

Workspace Commands TEAM

Command	Flags	Description
`evo ws init`	--name, --dir, --github, --branches, --override-branches, --team	Create workspace with workspace.json + config.
`evo ws add`	--name, --path, --repo, --color, --lang, --branches	Add child repo to workspace config.
`evo ws clone <url>`	positional	Clone workspace config repo and all child repos.
`evo ws integrate`	--format	Bootstrap .evolution/ in all child projects.
`evo ws validate`	(none)	Validation across all child projects.
`evo ws discover`	(none)	AI prompt for cross-service API link discovery.
`evo ws coherence`	(none)	Full workspace state + reconciliation.
`evo ws context`	(none)	Output nested .evolution/ files for LLM consumption.
`evo ws impact <project>`	positional	Impact analysis for modified microservice.
`evo ws conflict`	(none)	Detect uncommitted boundary collisions.
`evo ws github`	--public	Initialize GitHub repo via gh CLI.
`evo ws pr`	--ticket, --base, --dry	Coordinated cross-team PR workflow directive.
`evo ws deps`	(none)	Dependency freshness across all child projects.
`evo ws security`	(none)	Security scan across all child projects.
`evo ws sync`	(none)	Sync context for all workspace repos.

Repo Commands

Command	Flags	Description
`evo repo coherence`	--dir	Full repository state + reconciliation.
`evo repo schema`	--dir	Validate JSON architectural footprint.

Security & Dependencies

evo security

evo security --dir . --format json

Flag	Description
--no-audit	Skip dependency audit
--no-deps	Skip dependency freshness
--no-secrets	Skip secret detection
--no-code	Skip SAST (semgrep)
--no-infra	Skip IaC scanning
--no-supply	Skip supply chain
--no-containers	Skip container scanning
--history	Git history secret scan
--install-deps	Auto-install scanners

evo deps

evo deps --dir . --install-deps
evo deps remediate --dir . # AI remediation directive
evo deps automate --dir . # Generate dependabot.yml

Ecosystem coverage: npm, Go modules, Cargo, pip, Gradle, .NET, Terraform, Java, Swift, Ruby (Bundler). OSV.dev fallback for everything else.

Queue / Active Mesh

P2P agent mesh. Every identity has a queue at .evolution/active_mesh/queues/@<identity>/queue.json. Sync-pulse daemon auto-syncs via git.

Command	Flags	Description
`evo queue tree`	--dir, --parent*	Print parent→children tree.
`evo queue rollup-check`	--dir	Report parents eligible for auto-rollup.
`evo queue rollup`	--dir, --child*	Force EvaluateRollup.
`evo queue approve`	--dir, --id*	Approve review item + cascade.
`evo queue reject`	--dir, --id, --feedback, --target-children*	Route rework for specific children.

.evolution/ Directory

Every evo-managed project has a .evolution/ directory at its root:

.evolution/
├── directive.md # Agent instructions — read first
├── readme.md # Project README
├── spec.md # Architecture specification
├── roadmap.md # Planned work with status
├── tracking.md # Task tracking
├── bugs.md # Bug log
├── devqueue.md # Dashboard submissions
├── standards.md # Code standards
├── operator.md # Operator docs
├── features/ # Feature specs
├── meta/
│ ├── security.md # Scan results
│ ├── security.json
│ ├── architecture.json
│ ├── product-profile.json
│ ├── competitive.json
│ └── innovation.json
├── active_mesh/
│ ├── identity.json
│ └── queues/@<identity>/queue.json
└── sync_status.json

Org → Workspace → Repo

Strict 3-tier. Workspaces one directory deep from Org root. Repos one deep from Workspace root.

my-org/
├── .evolution/ # org.json, directive.md
├── platform-ws/
│ ├── .evolution/ # workspace.json, links.json
│ ├── api-gateway/
│ └── auth-service/
└── internal-tools/

1-Command Auto-Bootstrap

evo org discover \
--branches "development,staging,production" \
--override-branches "shared/*:main"

Omni-Orchestrator

evo org integrate \
--branches "dev,stg,prd" \
--override-branches "*-ops-*:staging"

Master Cascading Directive. Drop at empty org root — auto-bootstraps entire organization, maps Workspaces, templates Repos, traces terraform and API graphs in a single click.

Architecture Analysis

evo arch --dir .

Health score (0-100) with per-weakness deductions. Writes .evolution/meta/architecture.json.

What it checks

Category	Patterns Detected
Tech Stack	Go, Node, Rust, Python, Docker, K8s, Terraform
Lock Integrity	go.sum phantom entries, npm lock, Cargo.lock
Phantom Deps	Node.js imports not in package.json
Code Quality	God files (>600 lines), shared DB singletons, hardcoded secrets
Resilience	Health endpoints, circuit breakers, retry, panic recovery
Scalability	Metrics, tracing, sync.Mutex, N+1 queries
Security	Rate limiting, container config, IaC detection

Per-language Deep Patterns

Language	Detected Issues
Go	Goroutine leaks, naked returns, context ignored, error ignored, init() side effects, panic in lib
Node/TS	Unhandled promises, sync fs, console.log, excessive any, missing input validation
Python	Broad except, mutable defaults, global state, shell=True
Rust	unwrap(), unsafe blocks, clone-heavy
Swift	Force unwrap, retain cycles
Kotlin	Non-null assertion, GlobalScope coroutines

Intelligence / Competitive Analysis

evo profile # Product profile from spec.md + roadmap.md
evo compete # Market category match, competitor comparison
evo innovate # Prioritized: Catch-up → Differentiation → Blue Ocean

Three-stage pipeline. Writes to .evolution/meta/.

Desktop & Server

Server Mode

evo serve --dir . --port 8081

HTTP API with embedded Svelte SPA. 40+ endpoints. License gated.

Desktop Mode

evo desktop --dir . --port 8081

Native macOS via Wails v2 (1400×900). Auto-launches sync-pulse.

Dev builds: All features unrestricted. Production builds: Gate on serve/desktop. CLI commands unrestricted.

License & Activation

JWT-based (RS256). Offline verification.

evo activate --key <JWT>
evo status

Command	Description
`evo activate --key JWT`	Store license at ~/.evolution/license.jwt
`evo status`	Show email, tier, expiry, validity

Free Tier

spawn, integrate, validate, sync, arch, security, deps, profile, compete, innovate — no license needed.

Purchase: evolabz.org · Manage: Dashboard

evo Documentation