File-Backed Contracts Data Model
Relevant source files
The following files were used as context for generating this wiki page:
Delano utilizes a file-backed data model where the .project/ directory serves as the canonical source of truth for delivery contracts. This model ensures that planning, execution, validation, and evidence are kept on disk, allowing operators and coding agents to collaborate without vendor lock-in. The system treats these files as "local dossiers"—durable, human-readable, and machine-parsable artifacts.
Sources: README.md:10-12, DESIGN.md:129-131
Core Artifact Hierarchy
The data model is organized into a hierarchical structure within the .project/projects/<slug>/ directory. Each project consists of high-level specifications and plans, subdivided into workstreams and discrete tasks.
Project Structure Diagram
This diagram illustrates the relationship between the different file-based artifacts within a Delano project.
Artifact Definitions and Schemas
Each artifact type is a Markdown file containing YAML-like frontmatter for structured metadata and Markdown content for unstructured data.
1. Specification (spec.md)
Defines the project's measurable targets and high-level status. It includes metadata such as the owner, lead, and current project lifecycle state.
Sources: src/cli/lib/project-state.js:157, src/cli/lib/project-state.js:189-195
2. Delivery Plan (plan.md)
Maps out the generated artifacts and tracks the overall execution risk level and status.
Sources: src/cli/lib/project-state.js:158, src/cli/lib/project-state.js:196-199
3. Workstream (WS-X)
Logical groupings of tasks. Workstreams have their own lifecycle (planned, active, done, deferred) and act as parents to individual tasks.
Sources: src/cli/lib/project-state.js:216-234, src/cli/lib/project-state.js:630-638
4. Task (T-XXX)
The smallest unit of work. Tasks contain explicit dependency mapping and acceptance criteria.
Sources: src/cli/lib/project-state.js:241-267
| Field | Type | Description |
|---|---|---|
id | String | Canonical ID (e.g., T-001). |
status | Enum | ready, in-progress, blocked, done, deferred. |
workstream | String | Reference to the parent workstream ID (e.g., WS-A). |
depends_on | List | IDs of tasks that must be completed first. |
updated | ISO8601 | Last modified timestamp. |
blocked_owner | String | (Optional) Entity responsible for resolving a block. |
Sources: src/cli/lib/project-state.js:38-41, src/cli/lib/project-state.js:268-283, src/cli/lib/project-state.js:338-344
Lifecycle and Status Transitions
The data model enforces strict status transitions to maintain contract integrity. Changes to a task's status frequently trigger "rollups" to parent workstreams or the project spec/plan.
Task Status Flow
This sequence diagram shows how closing a task triggers automatic state updates across the project.
Contextual Data Layer
Beyond active project files, the model includes a context layer used to provide agents with repository-specific grounding. This is located in .project/context/.
| File | Purpose |
|---|---|
project-brief.md | Problem statement and target outcomes. |
tech-context.md | Technical stack and architecture. |
project-structure.md | Repository boundaries and runtime areas. |
system-patterns.md | Recurring logic and design patterns. |
progress.md | High-level roadmap and historical context. |
Sources: assets/templates/context/README.md:1-17, assets/templates/context/project-structure.md:1-20
Implementation Details: Frontmatter Parsing
The CLI manages these contracts by parsing and updating the frontmatter blocks in Markdown files.
// src/cli/lib/project-state.js:107-118
function parseFrontmatter(text) {
const match = text.match(/^---\n([\s\S]*?)\n---\n/);
if (!match) {
return {};
}
const result = {};
for (const line of match[1].split("\n")) {
const index = line.indexOf(":");
if (index === -1) continue;
result[line.slice(0, index).trim()] = line.slice(index + 1).trim();
}
return result;
}
Sources: src/cli/lib/project-state.js:107-118
Conclusion
The Delano File-Backed Contracts Data Model provides a decentralized, auditable, and tool-agnostic method for tracking software delivery. By utilizing simple Markdown files as the database, it ensures that project state is always available to both human operators and automated agents, maintaining a "local dossier" that serves as the definitive source of truth for the repository.
Sources: README.md:10-14, PRODUCT.md:13-18