How It Works¶
lazyai-cli uses a canonical-source-to-compile model. You edit one tool-agnostic layer; lazyai-cli generates the tool-native files. LazyAI owns the runtime/product surface that performs this setup, compilation, and local runtime-adjacent state management.
vibe-lab is an input to the product boundary: it supplies principles, assets, and adapter expectations that LazyAI may embed or adapt. It is not a runtime dependency, and LazyAI keeps execution ownership inside the LazyAI product.
Canonical source¶
The managed source of truth starts with .ai/ for MCP/catalog state and .specify/ for project constitution/templates:
.ai/
├── mcp.json
├── lazyai.json
├── lock.json
├── populate-needed
└── housekeeping/sync-state.json
.specify/
├── memory/constitution.md
└── templates/
These files are human-editable and version-controllable.
## Compiled output
From `.ai/`, `lazyai-cli compile` generates tool-native files such as:
- `AGENTS.md` — root instructions for all tools
- `opencode.json` — OpenCode agents, skills, commands, and MCP config (managed under top-level `mcp`)
- `.pi/` — Pi-compatible skills-only surface
- `.gemini/` — Antigravity settings and `hooks/lazyai/*`
- `.vscode/` — VS Code MCP config
```mermaid
flowchart TD
A[Canonical .ai/mcp.json] --> B[lazyai-cli compile]
B --> C["OpenCode opencode.json"]
B --> D[Claude Code .mcp.json or settings.local.json]
B --> E[Copilot .vscode/mcp.json]
B --> F[Pi skill-compatible output]
B --> G[Antigravity .gemini settings and hooks]
The active default adapter contract uses the front-door guide agent plus current canonical library content. implementer and the other specialists remain available, but simple sessions no longer start in implementation-first mode. Retired Fortnite defaults, old orchestrator runtime files, obsolete eval surfaces, and archived research/rollback material are not part of generated default runtime output.
Workflow¶
- Initialize once:
lazyai-cli init - Edit canonical files: change
.ai/mcp.json,.specify/memory/constitution.md, templates, or the relevant source docs/config for the setup - Recompile:
lazyai-cli compileorlazyai-cli update - Verify:
lazyai-cli doctorchecks drift and missing files
flowchart TD
A[lazyai-cli init] --> B{Scope selected}
B -->|project| C[Project .ai and .specify]
B -->|global| D[Home .ai and config]
B -->|workspace| E[Workspace planning repo]
C --> F[Scaffold managed files]
D --> F
E --> F
F --> G[Write .ai-setup store]
G --> H[lazyai-cli compile]
H --> I[Tool-native files]
I --> J[lazyai-cli doctor]
Manifest tracking¶
Every managed setup gets a manifest:
It tracks:
- setup scope and selected tools
- project/workspace metadata
- selected agents, skills, prompts, templates, and rules
- feature flags and git conventions
- managed file paths and content hashes
- operation history and sync metadata
This powers lazyai-cli status, lazyai-cli doctor, and lazyai-cli update.
Conflict and update behavior¶
| Situation | Behavior |
|---|---|
| Tracked + unchanged | Safely overwritten with latest managed content |
| Tracked + customized | Prompts/backs up before overwrite; --force auto-overwrites with backup |
| Existing untracked collision | Prompts before replacement; replacement creates backup |
| Newly expected file | Created and added to .ai-setup.db |
| Tracked but missing | Reported as missing, not silently recreated |
Backups are written under .ai-setup-backup/ with relative paths preserved.
TOML defaults¶
You can provide CLI defaults via TOML:
- Project:
.ai-setup.toml - Global:
~/.config/lazyai/config.toml
Precedence: CLI flags > project TOML > global TOML > built-in defaults
Execution model¶
- Local native agents are the intended execution path: Claude Code, OpenCode, and Copilot.
- A2A remains a config seam only and is not remote/network execution by default.
- Runtime-adjacent state in LazyAI is local: sessions, ledger, memory, messages, metrics, costs, and backups are optional CLI-managed state around the setup.
- Product scope is defined in Product Boundaries, including the shipped CLI command inventory, active embedded library, repository harness scripts, and retired/archived material.