Runtime Boundaries & Install Payload
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Delano runtime is designed as an agent-agnostic delivery system that prioritizes file-backed contracts. It establishes clear boundaries between the distribution layer (npm), the shared runtime (.agents/), and the repository-owned project state (.project/). The system is architected to be "conflict-first," ensuring that bootstrap operations do not inadvertently overwrite local state unless explicitly directed by an operator.
The install payload serves as the bridge between the packaged Delano logic and a target repository. It distributes approved scripts, schemas, hooks, and skills while maintaining a "local dossier" posture—treating the filesystem as the single source of truth for planning, execution, and validation.
Sources: README.md:12-25, src/cli/lib/install.js:150-165
Canonical Boundaries
Delano defines specific directory structures to maintain separation of concerns within a repository. These boundaries ensure that the operating model remains consistent across different coding agents and human operators.
Repository Areas
| Path | Role | Ownership |
|---|---|---|
HANDBOOK.md | Canonical operating model and rules | Delano / Repository |
.project/ | File-backed delivery contracts (specs, plans, tasks) | Repository-owned |
.agents/ | Shared runtime (scripts, rules, hooks, skills) | Delano-managed |
.delano/ | Read-only local viewer UI | Delano-managed |
.claude/ | Compatibility mirror for legacy agent paths | Delano-managed |
Sources: README.md:27-35, assets/templates/context/project-structure.md:5-15
Runtime Flow Overview
The following diagram illustrates how the Delano CLI interacts with these boundaries during a standard lifecycle.
Explanation: The diagram shows the Delano CLI deploying the install payload into specific repository boundaries, where scripts then operate on project contracts.
Sources: README.md:37-45, src/cli/index.js:30-65
Install Payload Management
The installation process is governed by a manifest-driven logic that categorizes files to allow for granular updates and repairs.
Install Categories
The system divides the payload into functional categories to support "update-safe" refreshes where project state is preserved while the runtime is upgraded.
| Category | Description | Primary Path(s) |
|---|---|---|
agent-runtime | Core scripts and operating rules | .agents/ (except skills) |
skills | Specialized agent capabilities | .agents/skills/ |
codex-hooks | Codex configuration and startup context | .codex/hooks.json |
project-context | Starter templates for project reality | .project/context/ |
project-templates | Artifact generation templates | .project/templates/ |
viewer | Read-only local UI components | .delano/viewer/ |
Sources: src/cli/lib/install.js:20-75
Installation Strategy Logic
Delano uses a specific logic to handle existing files, particularly for configuration files like Codex hooks which require merging rather than replacement.
Explanation: The installation flow involves plan building, filtering based on categories, and a conflict resolution phase that handles mergeable vs. force-overwritten assets.
Sources: src/cli/lib/install.js:460-520, README.md:200-215
Codex Hook Integration
A critical part of the install payload is the .codex/hooks.json file. Unlike standard assets, this file is merged into existing repository configurations to inject the Delano SessionStart hook without destroying existing user hooks.
Hook Merge Logic
- Detection: The installer checks if
.codex/hooks.jsonexists. - Validation: It ensures the existing file is valid JSON.
- Deduplication: It prevents duplicate injection of the
codex-session-status.jsscript. - Activation: Integration requires manual activation via
codex --enable hooks.
Sources: src/cli/lib/install.js:595-650, README.md:218-230
Runtime Validation & Safety
The runtime boundaries are enforced by a suite of validation scripts. These scripts ensure that the "local dossier" remains consistent and that agents do not breach safety boundaries.
Core Validation Checks
- Artifact Schemas: Ensures
.projectfiles match JSON schema definitions. - Status Transitions: Validates that tasks do not move to "done" if their parent workstream is "planned".
- Path Standards: Prevents the leakage of local absolute paths into shared contracts.
- Log Safety: Checks that committed logs do not contain raw sensitive prompts.
Sources: assets/install-manifest.json:60-90, AGENTS.md:35-45, README.md:265-275
Script Inventory Snippet
The following scripts (located in .agents/scripts/) define the runtime's validation layer:
# Validates all project contracts
bash .agents/scripts/pm/validate.sh
# Checks for path leakage and standards
bash .agents/scripts/check-path-standards.sh
# Verifies status transition integrity
node .agents/scripts/check-status-transitions.mjs
Sources: assets/install-manifest.json:80-110, AGENTS.md:28-33
Summary
The Runtime Boundaries and Install Payload of Delano establish a secure, file-backed environment for multi-agent delivery. By separating the immutable runtime scripts in .agents/ from the mutable, repository-owned state in .project/, Delano ensures that delivery truth remains traceable, verifiable, and independent of specific vendor workflows. The "conflict-first" installer and category-based updates allow maintainers to evolve the runtime without jeopardizing local project history.