File-backed delivery contracts for coding agents and operators.

Install · CLI · Viewer · Brand book · Handbook

Delano is an agent-agnostic delivery runtime. It keeps planning, execution, validation, and evidence on disk so maintainers, operators, and different coding agents can work from the same operating model without depending on one vendor workflow.

The product posture is a local dossier: warm paper, ledger ink, visible source paths, and quiet status signals. The interface and runtime both treat .project/ as the source of truth.

At a glance

Surface	Role
HANDBOOK.md	Canonical operating model
.project/	File-backed delivery contracts: specs, plans, workstreams, tasks, decisions, updates, evidence
.agents/	Shared runtime: scripts, rules, hooks, skills, adapters
.delano/	Read-only local viewer for inspecting .project state
docs/delano-brandbook.html	Brand book for the Delano visual language

Quick start

npx -y @bvdm/delano@latest --yes
npx -y @bvdm/delano@latest viewer
npx -y @bvdm/delano@latest validate

The viewer opens a localhost-only read surface for .project contracts. Validation checks that the runtime, contracts, package payload, and local gates still line up.

What Delano is

• HANDBOOK.md is the canonical operating model.
• .project/ is the delivery source of truth.
• .agents/ is the shared runtime: scripts, rules, hooks, skills, and adapters.
• .claude/ is a compatibility mirror of .agents/, not a second runtime.
• .delano/ is an optional UI layer.

The npm package is intentionally thin. It distributes the approved runtime payload, includes the read-only viewer UI, and wraps the existing shell-based PM scripts. It does not replace the handbook, the file contracts, or the underlying bash/Python execution layer.

Design language

Delano's visual system is intentionally quiet and document-like. The brand mark identifies the source; it does not decorate the interface.

• Creative north star: The Local Dossier.
• Palette: warm document ground, paper surface, ledger ink, hairline dividers, restrained slate selection, and forest identity through the logo assets.
• Typography: Inter for product and documentation text, JetBrains Mono for provenance and exact paths. Red Hat Display belongs only inside the supplied wordmark artwork.
• Shape: small 4px to 6px radii, 1px hairlines, open ledger rows instead of stacked cards.
• Motion: brief, functional feedback only.

See DESIGN.md and the Delano Brand Book for the full system.

Delano CLI

• Package: @bvdm/delano
• Current package version: 0.2.9
• Binary: delano
• Commands: onboarding, install, viewer, project, workstream, task, update, init, import-spec-kit, research, validate, status, next
• Primary goal: bootstrap a repo safely, expose local delivery state clearly, and keep runtime gates verifiable

Recent main changes

The latest main merges moved Delano beyond a thin install wrapper:

• PR #4, feat/delano-vnext-runtime-upgrade, merged on 2026-05-04. This added the v0.2 runtime layer: schema-backed .project artifact validation, operating-mode and status-transition checks, evidence mapping, strict validation fixtures, privacy-safe logging defaults, package/payload drift checks, dry-run sync inspection, apply-gated repair planning, lease-based multi-agent coordination, worktree health checks, delivery metrics, context audits, skill-output eval fixtures, and compact root/adapter agent instructions.
• PR #3, delano-viewer-design-overhaul, merged on 2026-04-29. This added the packaged read-only Delano viewer under .delano/viewer, including the local Node server, static UI, .project indexing APIs, project outlines, workstream/task navigation, rendered markdown, context-aware filters, guarded open actions, and visual/browser smoke evidence.

The current runtime still treats HANDBOOK.md and .project/ as the source of truth. The new pieces make that model easier to inspect and harder to bypass accidentally.

One-command bootstrap

To install the approved Delano runtime into the current repository:

npx -y @bvdm/delano@latest --yes

That shorthand is equivalent to:

npx -y @bvdm/delano@latest install --yes

To install into a different directory:

npx -y @bvdm/delano@latest --target <repo> --yes

If you already have the package installed locally, the same flow is:

delano --yes
delano --target <repo> --yes

Global CLI install

If you want delano available in every repository you work in, install it globally:

npm install -g @bvdm/delano

Typical flow in a repository:

cd <repo>
delano install --yes
delano viewer
delano validate
delano init <slug> "<Project Name>" [owner] [lead]
delano import-spec-kit <slug> <source-md> [--name <project-name>] [--owner <owner>] [--lead <lead>] [--json]
delano research <project-slug> <research-slug> [--title <title>] [--question <question>] [--json]

Command intent:

• delano install bootstraps the Delano runtime into the current repository
• delano viewer launches the read-only local UI for .project contracts
• delano validate checks whether the runtime and required assets are in place
• delano init creates a delivery project inside a repository that already has Delano installed
• delano import-spec-kit creates a planned Delano project from the first supported Spec Kit-style markdown fixture and then runs validation
• delano research creates repo-native research intake files inside an existing Delano project and then runs validation

delano init usage:

delano init <slug> "<Project Name>" [owner] [lead]

Notes:

• use kebab-case for <slug>
• owner defaults to team
• lead defaults to owner
• this is the right command for an agent to scaffold a new delivery project after delano install

delano import-spec-kit usage:

delano import-spec-kit <slug> <source-md> [--name <project-name>] [--owner <owner>] [--lead <lead>] [--json]

Notes:

• the source markdown must use the initial supported shape documented in docs/spec-kit/import-contract.md
• agents should prefer named options over positional metadata, and --json when parsing the result
• imported artifacts start in planned/ready states and still have to pass Delano validation, probe, and evidence gates
• the command is additive and refuses to overwrite an existing .project/projects/<slug>/ folder

delano research usage:

delano research <project-slug> <research-slug> [--title <title>] [--question <question>] [--owner <owner>] [--json]

Notes:

• use this before mutating spec.md, plan.md, workstreams, or tasks when intent is unclear
• research files live under .project/projects/<project-slug>/research/<research-slug>/
• agents should use --json when parsing the result
• research findings must fold forward into canonical Delano artifacts or be explicitly closed as no-action

How to use Delano after install

For a fast guided path, start with Delano in the First 15 Minutes.

Recommended first step:

delano onboarding

delano onboarding searches upward for AGENTS.md, asks for explicit approval before it analyzes anything, and prints recommendations using the packaged onboarding skill rubric. It does not edit AGENTS.md on its own.

If you bootstrap with one-shot npx, keep using npx for wrapper commands:

npx -y @bvdm/delano@latest onboarding --approve-agents-analysis
npx -y @bvdm/delano@latest viewer
npx -y @bvdm/delano@latest validate
npx -y @bvdm/delano@latest status
npx -y @bvdm/delano@latest status --open --brief
npx -y @bvdm/delano@latest next -- --all

If the package is installed locally or globally, run these inside the target repository:

delano onboarding
delano viewer
delano validate
delano status
delano status --open --brief
delano next -- --all
delano init <slug> "<Project Name>" [owner] [lead]
delano import-spec-kit <slug> <source-md> --json
delano research <project-slug> <research-slug> --title "Research title" --question "Primary question" --json

The wrapper commands call the existing PM scripts under .agents/scripts/pm/. You can also run those scripts directly:

bash .agents/scripts/pm/validate.sh
bash .agents/scripts/pm/status.sh
bash .agents/scripts/pm/status.sh --open --brief
bash .agents/scripts/pm/next.sh --all
bash .agents/scripts/pm/research.sh <project-slug> <research-slug> --title "Research title" --question "Primary question" --json

Local viewer

The viewer is packaged with @bvdm/delano and serves the selected repository's .project files read-only. It defaults to http://127.0.0.1:3977; set DELANO_VIEWER_PORT or PORT to use another port.

It indexes .project/context, .project/templates, and .project/projects, then derives artifact roles, statuses, project outlines, task/workstream relationships, snippets, and rendered markdown for local inspection.

The viewer follows the same design language as the brand book: source paths stay visible, status is shown with labels and dots, and dense project state is separated with hairlines rather than decorative cards.

Required dependencies

Delano assumes these tools are available:

• node 18 or newer
• bash
• git
• python3 or compatible python / py

The CLI does not bundle its own shell or Python runtime.

Install behavior

delano install is conflict-first by default:

• it computes the full install plan before writing files
• it aborts if an approved target path already exists
• it reports each conflict as file, directory, or symlink
• it only overwrites approved allowlist paths when --force is used
• it can narrow updates with --only, --exclude, --no-project-context, and --no-project-state
• it does not touch unrelated files outside the allowlist
• it does not install or overwrite repo-root Git config files such as .gitignore or .gitattributes

The base install payload intentionally excludes top-level adapter entry docs such as AGENTS.md, CLAUDE.md, CODEX.md, OPENCODE.md, and PI.md. Those remain opt-in only. The base install payload includes .delano/, including the read-only viewer UI. The base install payload also includes .codex/hooks.json, a Codex SessionStart hook config that injects compact open-project context when Codex hooks are enabled. If a target repo already has .codex/hooks.json, delano install merges the Delano hook into the existing JSON instead of replacing it. Invalid or non-file hook configs are skipped without blocking the rest of the install.

Codex hook activation is intentionally manual:

1. Enable hooks for a session with codex --enable hooks, or persist the feature in ~/.codex/config.toml:

   [features]
   hooks = true

2. Start Codex in the repository and approve the project trust prompt for the repo-local .codex/ layer. Codex records trusted projects in ~/.codex/config.toml, for example:

   [projects."<repo>"]
   trust_level = "trusted"

3. Approve the Delano SessionStart hook when Codex asks whether to trust it.

Older docs and builds may refer to [features].codex_hooks; newer Codex builds warn that this key is deprecated in favor of [features].hooks.

The installable .project/context/ pack is seeded from generic templates during packaging; it does not ship Delano's own repo-specific context files into consumer repositories. After install, the recommended first step is delano onboarding, which requires explicit approval before it reviews AGENTS.md.

For an update-safe refresh that avoids repo-owned project state, narrow the plan before forcing overwrites:

delano install --interactive
delano install --only skills,project-templates --force --yes
delano install --exclude project-context,project-projects,project-registry --force --yes
delano install --no-project-state --force --yes

The interactive installer presents presets for updating the runtime while preserving project state, updating only skills and project templates, full install or repair, and custom category selection.

Install categories are agent-runtime, codex-hooks, skills, viewer, project-context, project-templates, project-registry, project-projects, handbook, and legacy-installer. The --no-project-state shortcut excludes .project/context, .project/projects, and .project/registry.

Optional AGENTS.md / CLAUDE.md snippet

If you want explicit Delano instructions in a repo-root AGENTS.md or CLAUDE.md, copy and paste this yourself:

## Delano

This repository uses Delano.

Canonical process and contracts live in `HANDBOOK.md`.
Delivery state lives in `.project/`.
Shared runtime lives in `.agents/`.
`.claude/` is a compatibility mirror of `.agents/`, not a second runtime.

When working in this repository:
- treat `.project/` as the source of truth
- use the Delano status model and evidence discipline from `HANDBOOK.md`
- keep sync and quality gates aligned with the handbook
- use `delano init <slug> "<Project Name>" [owner] [lead]` to scaffold a new delivery project when needed
- use `delano viewer` to inspect `.project/` through the read-only local UI

Runtime boundaries

This package is deliberately narrow:

• npm is the distribution surface
• .project remains repo-owned after install
• .project/context/ installs as generic starter context that the target repo must replace with its own reality
• .project/projects/ and .project/registry/ are repo-owned state and should normally be excluded from forced refreshes
• .agents remains the runtime surface
• wrapper commands stay thin
• install-delano.sh remains available as the legacy bridge installer
• remote GitHub/Linear writes remain outside the default flow; current sync tooling is dry-run and repair-plan oriented unless an operator explicitly approves an apply-capable workflow

Runtime validation

The v0.2 runtime upgrade expanded delano validate and bash .agents/scripts/pm/validate.sh with local gates for:

• artifact schemas, artifact scope, operating modes, status transitions, dependencies, blockers, and acceptance/evidence mapping
• privacy-safe prompt/log defaults and path-output safety
• package manifest and install payload drift
• local/GitHub/Linear sync inspection, drift reporting, and apply-gated repair planning
• lease contracts, conflict zones, stream-aware next-task selection, handoff summaries, and worktree health
• delivery metrics, project metrics summaries, context audit scoring, skill-output eval fixtures, and closeout learning proposals

For release readiness, run:

npm run build:assets
npm run check:package-manifest
bash .agents/scripts/pm/validate.sh
npm test

Local development

From this repository:

npm run build:assets
node bin/delano.js --help
node bin/delano.js --yes --target ./tmp/cli-install-smoke

Publishing

Publishing is handled by the GitHub Actions workflow .github/workflows/publish-npm.yml.

Before the first Actions publish, configure npm trusted publishing for @bvdm/delano with:

• Publisher: GitHub Actions
• Organization or user: MajesteitBart
• Repository: delano
• Workflow filename: publish-npm.yml

The package metadata must keep repository.url set to https://github.com/MajesteitBart/delano; npm validates that value against the GitHub Actions provenance bundle.

After trusted publishing is configured, publish by pushing a matching version tag such as v0.2.4, or run the Publish package to npm workflow manually from main. The workflow rebuilds the package payload, checks manifest drift, runs tests, dry-runs the package contents, verifies the version is not already published, and then runs npm publish --access public from GitHub Actions using OIDC. A manual dry_run input is available to run the same checks without publishing.

If npm publish fails after the package checks pass, verify that the npm trusted publisher settings match the repository and workflow filename exactly, and that the workflow has id-token: write.

Read next

• docs/README.md for the user documentation index
• docs/user-guide.md for the practical user flow
• docs/cli-reference.md for the CLI command reference
• docs/viewer-guide.md for the read-only viewer workflow
• docs/agent-operator-guide.md for instructing agents
• docs/spec-kit-and-research.md for Spec Kit-style import and research intake
• HANDBOOK.md for the full operating model
• .agents/scripts/README.md for the runtime script inventory
• AGENTS.md for adapter-neutral instructions