Operating Modes
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Operating Modes in Delano define the strict behavioral boundaries and governance levels for agents and operators interacting with the repository. These modes ensure that the file-backed delivery contracts within the .project/ directory remain the source of truth while providing clear constraints on when an agent can move from planning to execution. The system transitions through levels (referenced as modes 0 through 4) to manage risk, uncertainty, and evidence requirements during the project lifecycle.
These modes are integrated into the Delano v0.2 runtime upgrade, which introduced schema-backed artifact validation and operating-mode checks. By enforcing these modes, Delano prevents accidental bypasses of the canonical operating model defined in HANDBOOK.md.
Sources: README.md:25-30, README.md:143-150, test/package.test.js:192-198
Mode Architecture and Lifecycle
The operating mode system is governed by a set of transitions and validation rules stored within the .agents/schemas/ directory. The runtime uses these schemas to verify that a project or task is in a valid state before allowing specific actions, such as starting work or closing a task.
Mode Definition and Validation
Operating modes are defined in operating-modes.json and enforced via runtime validation scripts. The system tracks whether a project is in a "planned," "active," or "complete" state, with specific modes governing the depth of evidence required.
The diagram above shows the linear progression of operating modes and the validation gates that monitor them.
Sources: assets/install-manifest.json:49-51, test/package.test.js:192-198
Lifecycle Transitions
The project state is managed through the CLI and underlying logic in project-state.js. Actions like start, close, block, or defer trigger state rollups that affect the operating mode of the entire project.
| Mode/Status | Context | Significance |
|---|---|---|
| Planned | Spec/Plan are created but not active | Research and scoping phase. |
| Active | Execution in progress | Mode 3; Requires evidence logging and task tracking. |
| Complete/Done | All tasks resolved | Mode 4; Requires closeout learning and metric summaries. |
| Deferred | Execution paused | Mode-safe suspension of workstreams. |
Sources: src/cli/lib/project-state.js:370-385, src/cli/lib/project-state.js:460-475
Technical Implementation
State Rollup Logic
When a task action occurs, the system automatically promotes the project and workstream status to "active" if they were previously "planned". This ensures the operating mode correctly reflects current activity.
function promoteProjectToActive(project, timestamp, changes) {
if (project.spec && ["planned", "complete", "deferred"].includes(project.spec.frontmatter.status || "")) {
setSpecStatus(project, "active", timestamp, changes);
}
if (project.plan && ["planned", "done", "deferred"].includes(project.plan.frontmatter.status || "")) {
setPlanStatus(project, "active", timestamp, changes);
}
}
Sources: src/cli/lib/project-state.js:536-543
Validation Checks
The Delano runtime validates operating modes through several specialized scripts:
check-operating-modes.mjs: Ensures the current state matches one of the five defined levels (0-4).check-status-transitions.mjs: Prevents invalid transitions, such as moving to "done" while the project is still in a "planned" mode.check-evidence-map.mjs: Verifies that evidence requirements for the current mode are met.
Sources: assets/install-manifest.json:71-76, test/package.test.js:203-210
Multi-Agent Coordination
In complex operating environments, Delano uses lease-based coordination to prevent conflicts between multiple agents working in the same "mode." This involves lease-manager.mjs and check-lease-conflicts.mjs.
This sequence ensures that only one agent holds an exclusive lease on a specific "zone" of the project during execution.
Sources: test/package.test.js:352-365, assets/install-manifest.json:84-86
Conclusion
Operating Modes in Delano provide a structured framework for repository evolution. By moving from Discovery (0) through Closeout (4), the system ensures that every change is backed by a contract, every action is validated against a schema, and evidence is recorded before a mode is considered complete. This model allows for agent-agnostic delivery where the state of work is always visible and verifiable on disk.
Sources: README.md:143-155, PRODUCT.md:20-25