Introduction to Delano
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 file-backed delivery contracts for coding agents and human operators. It centralizes planning, execution, validation, and evidence directly on the file system, ensuring that different vendors and operators work from a single operating model without dependency on proprietary workflows. The system treats the .project/ directory as the absolute source of truth for all delivery state.
Sources: README.md:10-14, PRODUCT.md:12-16
The platform adopts a "Local Dossier" posture, emphasizing legibility, trust, and visible provenance. It provides a thin CLI for bootstrapping and state management, alongside a read-only local viewer for inspecting the state of projects, workstreams, and tasks.
Sources: README.md:16-17, DESIGN.md:90-94
Core Architectural Components
Delano's architecture is distributed across several key directories within a repository, each serving a distinct role in the delivery lifecycle.
| Surface | Description |
|---|---|
HANDBOOK.md | The canonical operating model and process guide. |
.project/ | File-backed delivery contracts (specs, plans, workstreams, tasks, decisions). |
.agents/ | Shared runtime containing scripts, rules, hooks, skills, and adapters. |
.delano/ | Optional UI layer containing the read-only local viewer. |
.claude/ | A compatibility mirror of .agents/ for specific agent expectations. |
Sources: README.md:21-29, AGENTS.md:17-23
The .project/ Structure
The .project/ directory is the repository-owned source of truth. It contains templates used for scaffolding and individual project directories that house markdown-based contracts.
The diagram shows how delivery contracts are organized within the .project/ directory.
Sources: src/cli/lib/project-state.js:93-100, README.md:168-175
State Management and Lifecycle
Delano manages the lifecycle of projects through automated "rollups." When a task's status changes (e.g., from ready to in-progress), the system automatically promotes the parent workstream and project statuses to active.
Task Status Transitions
Tasks follow a strict lifecycle managed by the CLI. Closing a task requires evidence and can trigger the automatic opening of dependent tasks if their blockers are removed.
Logic for task transitions and lifecycle events.
Sources: src/cli/lib/project-state.js:8-9, src/cli/lib/project-state.js:338-360
Automated Rollup Logic
The runtime ensures that parent containers (Workstreams and Projects) accurately reflect the state of their children.
- Start/Close Task: Promotes planned projects and workstreams to
active. - Close/Defer Task: If no open tasks remain, the parent workstream is marked
done. - Completion: When all tasks are closed, the project
spec.mdis markedcompleteandplan.mdis markeddone.
Sources: src/cli/commands/state.js:96-101, src/cli/lib/project-state.js:364-380
CLI and Runtime Scripts
The Delano CLI (@bvdm/delano) acts as a wrapper for underlying bash and Python execution layers. It provides commands for onboarding, installation, and state manipulation.
Key CLI Commands
delano install: Bootstraps the runtime into a repository.delano project create: Scaffolds a new project from templates.delano task start/close: Manages individual unit-of-work state.delano viewer: Launches a local Node.js server to browse the.projectstate athttp://127.0.0.1:3977.
Sources: README.md:52-60, src/cli/index.js:46-64
Validation Engine
The v0.2 runtime upgrade introduced extensive validation via delano validate. This checks:
- Artifact Schemas: Ensures markdown frontmatter and structure match expected types.
- Status Transitions: Validates that state changes follow allowed paths.
- Evidence Mapping: Confirms that closures have associated proof trails.
- Log Safety: Checks for leaked absolute paths or private data in logs.
Sources: README.md:200-210, AGENTS.md:51-55
Design Language: The Local Dossier
The Delano Viewer and documentation follow a specific visual system defined as "The Local Dossier." This system prioritizes function and provenance over decoration.
- Palette: Warm document grounds (
oklch(0.985 0.004 85)), ledger ink, and slate accents for active states. - Typography: Inter for UI and JetBrains Mono for paths and technical provenance.
- Components: Uses "ledger rows" and 1px hairlines instead of traditional cards or shadows.
Sources: DESIGN.md:6-30, DESIGN.md:96-105
Visual hierarchy and principles of the Delano design system.
Sources: PRODUCT.md:30-36, DESIGN.md:120-130
Conclusion
Delano provides a structured, file-backed environment for complex technical delivery. By codifying project state into markdown contracts and providing an agent-agnostic runtime, it bridges the gap between human operators and automated coding agents, ensuring that the source of truth remains local, readable, and verifiable.
Sources: PRODUCT.md:18-22, README.md:10-12