Operating Model & Handbook
Relevant source files
The following files were used as context for generating this wiki page:
Delano is an agent-agnostic delivery runtime designed to maintain a consistent operating model across different coding agents and human operators. The HANDBOOK.md file serves as the canonical operating model, defining the rules, processes, and delivery contracts that govern how work is planned, executed, and validated within a repository. By keeping planning and evidence on disk in a standardized format, Delano ensures that the source of truth remains independent of any specific vendor workflow.
The core philosophy of the Delano operating model is the "Local Dossier"—a posture characterized by visible source paths, traceable evidence, and quiet status signals. The system treats the .project/ directory as the primary source of truth for delivery state, while .agents/ provides the shared runtime assets necessary to execute the model.
Sources: README.md:9-14, PRODUCT.md:14-18, DESIGN.md:54-58
Repository Architecture & Boundaries
The Delano operating model is enforced through a specific directory structure that separates the canonical rules from the active delivery state and the execution runtime.
Canonical Boundaries
The repository is divided into several primary areas, each with a distinct role in the operating model:
| Surface | Role | Description |
|---|---|---|
HANDBOOK.md | Canonical Operating Model | Defines the rules of engagement and the standard delivery process. |
.project/ | Delivery Source of Truth | Contains file-backed contracts: specs, plans, workstreams, tasks, and evidence. |
.agents/ | Shared Runtime | Includes scripts, rules, hooks, skills, and adapters for automated agents. |
.delano/ | UI/Viewer Layer | An optional, read-only local viewer for inspecting the state of .project. |
.claude/ | Compatibility Mirror | A mirror of .agents/ provided for agents expecting legacy path structures. |
Sources: README.md:20-29, assets/templates/context/project-structure.md:5-13
Logical Data Flow
The following diagram illustrates how information flows from the canonical handbook through the runtime to the final delivery artifacts on disk.
The runtime treats .project/ as the immutable source of truth for current state, while HANDBOOK.md provides the logic for how that state is allowed to transition.
Sources: README.md:31-38, AGENTS.md:15-20
Delivery Contracts & Artifacts
The Delano operating model relies on standardized Markdown files with YAML-like frontmatter to track project progression. These artifacts are stored within .project/projects/<slug>/.
Core Artifact Types
- Spec (
spec.md): Defines the measurable targets, uncertainty levels, and overall project status (e.g.,planned,active,complete). - Plan (
plan.md): Outlines the delivery strategy, risk levels, and the generated artifact map. - Workstreams (
workstreams/): Logical groupings of tasks (e.g.,WS-A). They aggregate the status of their underlying tasks. - Tasks (
tasks/): The smallest unit of work (e.g.,T-001). Tasks include dependencies (depends_on), priority, and evidence logs.
Sources: src/cli/lib/project-state.js:77-84, src/cli/lib/project-state.js:180-210
Lifecycle & Status Transitions
The operating model enforces strict status transitions. A project or workstream cannot be "Done" if it contains tasks that are still "In-Progress" or "Ready."
Lifecycle rollups are a key feature of the CLI: starting or closing a task automatically promotes the parent workstream and project to active. Conversely, closing the final task in a workstream marks that workstream as done.
Sources: src/cli/lib/project-state.js:347-362, src/cli/commands/state.js:95-101
Execution Model for Agents
The "First-turn workflow" is the standard procedure for any coding agent operating under the Delano model. It emphasizes inspection and validation before modification.
The First-turn Workflow
Agents are instructed to follow a specific sequence to maintain repository integrity:
- Read Context: Start with
AGENTS.mdand agent-specific adapter notes. - Inspect State: Run
git statusand check the relevant.project/contracts. - Smallest Change: Implement the smallest task-safe change.
- Validate: Run
bash .agents/scripts/pm/validate.sh. - Record Evidence: Log completion evidence directly into the task or project updates before committing.
Sources: AGENTS.md:5-13, README.md:111-120
Agent Safety Boundaries
The operating model prohibits destructive actions and ensures privacy through specific safety checks.
Sources: AGENTS.md:32-38, README.md:144-154
Validation & Verification
Validation is a core pillar of the Delano operating model. It ensures that the files on disk conform to the schemas and rules defined in the handbook.
Validation Gates
The v0.2 runtime expanded delano validate to include checks for:
- Artifact Schemas: Ensuring frontmatter and structure are correct.
- Status Transitions: Verifying that status changes follow the allowed state machine.
- Dependency Health: Checking for broken dependencies (e.g., Task B cannot start if Task A is not done).
- Safety: Privacy-safe logging defaults and path-output safety.
- Drift: Detecting drift between the installed runtime payload and the manifest.
Sources: README.md:144-154, src/cli/lib/project-state.js:511-522
Design Language: The Local Dossier
The operating model extends into the visual representation of data via the Delano Viewer. The design language is "Quiet" and "Document-like," prioritizing readability and provenance.
- Palette: Warm document ground (
oklch(0.985 0.004 85)) and ledger ink. - Typography: Inter for product text and JetBrains Mono for exact paths and timestamps.
- Components: Uses "Ledger Rows" instead of cards to present dense information without unnecessary decoration.
- Visual Trust: Provenance and source paths must always remain visible to the operator.
Sources: DESIGN.md:3-15, DESIGN.md:59-65, PRODUCT.md:21-25
Conclusion
The Delano Operating Model & Handbook transform project management from a vendor-locked SaaS experience into a file-backed, local-first workflow. By codifying rules in HANDBOOK.md and maintaining state in .project/, Delano enables a high-trust environment where agents and human operators can collaborate using a shared, verifiable source of truth. The model's emphasis on evidence logging, automated lifecycle rollups, and rigorous validation ensures that delivery remains traceable and accurate throughout the software development lifecycle.
Sources: README.md:15-18, PRODUCT.md:14-18