Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Delano is an agent-agnostic delivery runtime that utilizes file-backed delivery contracts to coordinate work between human operators and coding agents. The system treats the local filesystem, specifically the .project/ directory, as the single source of truth for planning, execution, and evidence. By maintaining state in flat files, Delano avoids vendor lock-in and provides a transparent operating model that can be inspected by any tool or person.
Sources: README.md:14-18, PRODUCT.md
1. System Components
The Delano architecture is composed of four primary surface areas that define the operating environment and data boundaries.
Core Architecture Boundaries
| Surface | Directory/File | Role |
|---|---|---|
| Operating Model | HANDBOOK.md | The canonical rules for the repository's delivery process. |
| Delivery State | .project/ | Contains the actual contracts: specs, plans, tasks, and evidence. |
| Shared Runtime | .agents/ | Houses the scripts, hooks, rules, and skills used for execution. |
| Presentation Layer | .delano/ | A read-only local viewer for inspecting project state. |
Sources: README.md:24-30, assets/templates/context/project-structure.md:6-12
Component Relationship Diagram
The following diagram illustrates how the CLI and Viewer interact with the file-backed source of truth.
The diagram shows the central role of the .project/ directory as the hub for all Delano operations. Sources: README.md:144-150, src/cli/lib/project-state.js:101-115
2. Data Model & State Management
Delano manages state through structured Markdown files with YAML-like frontmatter. This allows for both human readability and machine parsability.
Artifact Hierarchy
- Project (
spec.md,plan.md): The high-level definition of what is being built and how. - Workstreams (
workstreams/*.md): Logical groupings of related tasks. - Tasks (
tasks/*.md): The smallest unit of trackable work, containing IDs likeT-001. - Updates & Evidence: Logs and files that prove completion or explain blockers.
Sources: src/cli/lib/project-state.js:101-115, README.md:162-178
Lifecycle Transitions
Task and project states follow a strict progression managed by the project-state.js library.
This flowchart represents the task status transitions enforced by the runtime. Sources: src/cli/lib/project-state.js:460-500, README.md:182-188
3. The Delano CLI & Runtime
The CLI (distributed via @bvdm/delano) serves as a wrapper for underlying shell scripts and provides high-level commands for state manipulation.
Key Logic Modules
project-state.js: Handles file I/O, frontmatter parsing, and template rendering for projects, workstreams, and tasks.runtime.js: Locates the Delano root and manages execution paths for scripts.commands/state.js: Implements the business logic for lifecycle actions likestart,close, andblock.
Sources: src/cli/index.js:35-55, src/cli/lib/project-state.js:1-15
Automated Rollups
When a task's status changes, the system automatically "rolls up" these changes to parent entities. For example, starting a task promotes its parent workstream and the overall project plan to active. Closing the final task in a workstream marks that workstream as done.
Sources: src/cli/lib/project-state.js:512-535
4. Local Viewer Architecture
The Delano Viewer is a "Local Dossier" designed for high-fidelity inspection of the delivery state.
- Technology: Node.js server (
server.js) serving a React/browser-based UI. - Design Philosophy: Uses "Ledger Ink" and "Warm Paper" aesthetics to feel like an operational document rather than a flashy dashboard.
- Functionality: Indexes
.project/files to derive relationships between tasks and workstreams, rendering Markdown for easy reading.
Sources: DESIGN.md:10-35, README.md:131-138, package.json:20
Viewer Interaction Flow
The sequence shows how the viewer dynamically indexes the filesystem to present current state. Sources: README.md:131-138, DESIGN.md:280-295
5. Security & Safety Boundaries
The architecture includes specific gates to ensure privacy and repository integrity:
- Privacy-Safe Logging: Raw prompts are opt-in only, and logs are checked for sensitive data.
- Path Safety: The system prohibits leaking absolute local paths in documentation or contracts.
- Conflict-First Install: The installer computes plans and aborts if approved paths are occupied unless
--forceis used.
Sources: AGENTS.md:38-45, README.md:154-165
Summary
Delano’s architecture is defined by its commitment to "File-backed delivery contracts." By offloading state to the filesystem and providing a thin, script-based runtime, it ensures that project management data is as durable and versionable as the source code itself. The separation of the shared runtime (.agents/), the state (.project/), and the viewer (.delano/) allows for a modular, transparent workflow suitable for both human-led and agent-assisted development.