Installation & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
Delano is an agent-agnostic delivery runtime designed to manage planning, execution, and validation through file-backed contracts. The installation process bootstraps a repository with the necessary structures—primarily .project/, .agents/, and .delano/—to enable a shared operating model between human operators and coding agents. Sources: README.md:9-14, PRODUCT.md
The installation system prioritizes safety through a conflict-first approach, computing a full plan before writing any files. It distinguishes between the shared runtime payload and repo-owned state, such as project context and registries, which are typically preserved during updates. Sources: README.md:144-152, src/cli/lib/install.js:336-340
Installation Methods
NPX One-Command Bootstrap
The most direct way to install the Delano runtime into a repository is using npx. This ensures the latest version of the CLI is used to bootstrap the local environment.
npx -y @bvdm/delano@latest --yes
This command is a shorthand for delano install --yes. To target a specific directory other than the current one, use the --target flag. Sources: README.md:107-123, src/cli/index.js:77-88
Global CLI Installation
For users working across multiple repositories, the CLI can be installed globally via npm:
npm install -g @bvdm/delano
Sources: README.md:125-127
Legacy Shell Bridge
A bash-based installer (install-delano.sh) is provided as a migration bridge. It uses git sparse-checkout to pull specific paths from the source repository. This method is recommended only until the npm-based flow is fully adopted. Sources: install-delano.sh:19-27, README.md:195
Installation Architecture
The installation logic is handled by the runInstall function, which orchestrates argument parsing, plan building, conflict detection, and file application.
The installation flow ensures no files are overwritten without explicit --force or user approval. Sources: src/cli/commands/install.js:52-85, src/cli/lib/install.js:336-350
Install Categories
The payload is organized into logical categories, allowing users to narrow the installation or update specific parts of the runtime.
| Category | Description | Path Match |
|---|---|---|
agent-runtime | Core scripts, rules, and schemas | .agents/ (excluding skills) |
skills | Agent skill definitions | .agents/skills/ |
codex-hooks | Codex configuration and status hooks | .codex/, .agents/hooks/ |
viewer | Local read-only UI files | .delano/ |
project-context | Starter context templates | .project/context/ |
project-templates | Markdown templates for tasks/specs | .project/templates/ |
handbook | Canonical operating model | HANDBOOK.md |
Sources: src/cli/lib/install.js:16-65
Configuration & Customization
Install Presets
The CLI provides presets to simplify common installation and update scenarios. Sources: src/cli/lib/install.js:84-114
| Preset ID | Label | Behavior |
|---|---|---|
update-safe | Update runtime, preserve state | Forces refresh but excludes .project/ state |
skills-templates | Update skills and templates | Refreshes only .agents/skills and .project/templates |
full | Full install or repair | Installs every allowlisted category including starter state |
custom | Choose categories | Allows manual selection of categories via TUI |
Codex Hook Integration
Delano includes a SessionStart hook for the Codex agent. If .codex/hooks.json already exists in the target repo, the installer merges the Delano hook into the existing JSON rather than overwriting it. This hook provides startup context by running .agents/hooks/codex-session-status.js. Sources: src/cli/lib/install.js:435-470, README.md:156-161
Quick Start Workflow
Once Delano is installed, the following sequence is recommended to initialize project delivery:
- Onboarding: Run
delano onboardingto analyze the repository'sAGENTS.mdand ensure compliance with the Delano operating model. Sources: README.md:200-205 - Project Initialization: Create a new delivery contract.
Sources: README.md:131-136delano init <slug> "<Project Name>" [owner] [lead] - Launch Viewer: Open the read-only local UI to inspect the state.
Sources: README.md:129delano viewer - Validation: Ensure the runtime and contracts are aligned.
Sources: README.md:130delano validate
Dependency Requirements
Delano assumes the following tools are present in the environment:
- Node.js: version 18 or newer
- Bash: for running PM scripts
- Git: for versioning and sparse-checkout
- Python3: for specific execution layers
Sources: README.md:214-220, package.json:20-22
Summary
Installation in Delano is a controlled process that bootstraps the .project/ delivery source of truth and the .agents/ shared runtime. By utilizing the NPM package @bvdm/delano, users can safely install the runtime, manage updates via category filtering, and integrate with agents like Codex through automated hook merging. The system is designed to be "conflict-first," ensuring that repository-specific project state is protected during runtime upgrades. Sources: README.md:25-45, src/cli/lib/install.js:352-378