Artifact Schemas & Scope
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Artifact Schemas & Scope defines the structural integrity and boundary definitions for the Delano delivery runtime. Delano operates as a file-backed system where project state—including specifications, plans, workstreams, and tasks—is stored as Markdown files with structured frontmatter. The system uses a set of JSON schemas and validation logic to ensure that these files, referred to as "artifacts," remain consistent, traceable, and compliant with the project's operating model.
The scope of these artifacts is confined to the .project/ directory, which serves as the canonical source of truth for delivery contracts. This structure allows agents and human operators to work from a shared model of execution, validation, and evidence without vendor lock-in. The runtime validates these artifacts against defined schemas to prevent state drift and ensure that lifecycle transitions (such as moving a task from ready to in-progress) follow mandatory logical gates.
Sources: README.md:14-18, test/package.test.js:255-270, src/cli/lib/project-state.js:100-110
Artifact Architecture & Hierarchy
Delano artifacts are organized hierarchically within the .project/projects/<slug>/ directory. The architecture separates high-level intent (Spec and Plan) from execution details (Workstreams and Tasks).
Core Artifact Types
The system recognizes several primary artifact types, each governed by specific requirements and frontmatter fields.
| Artifact | Purpose | Primary Location |
|---|---|---|
Spec (spec.md) | Defines the measurable target, uncertainty, and outcome. | .project/projects/<slug>/spec.md |
Plan (plan.md) | Outlines delivery strategy, risk levels, and artifact maps. | .project/projects/<slug>/plan.md |
Decision Log (decisions.md) | Records architectural and project-level decisions. | .project/projects/<slug>/decisions.md |
| Workstream | Groups related tasks into functional areas. | .project/projects/<slug>/workstreams/ |
| Task | The smallest unit of executable work. | .project/projects/<slug>/tasks/ |
| Update | Records point-in-time progress or blockers. | .project/projects/<slug>/updates/ |
Sources: src/cli/lib/project-state.js:102-108, assets/install-manifest.json:33-43, README.md:105-115
Artifact Relationship Model
The following diagram illustrates how artifacts relate to one another within a project scope.
The diagram shows the ownership hierarchy where a Project slug contains singular Spec and Plan files, while owning multiple Workstreams and Tasks.
Sources: src/cli/lib/project-state.js:100-108, src/cli/commands/state.js:100-115
Schema Enforcement & Validation
Validation in Delano is a multi-layered process that checks for structural compliance, status transition logic, and evidence requirements.
Frontmatter Schemas
Every artifact starts with a YAML frontmatter block. The src/cli/lib/project-state.js library provides the parseFrontmatter and setFrontmatter functions to manipulate these fields. The runtime enforces specific fields for different artifacts to maintain the "delivery contract."
- Task Schema Requirements: Tasks must include
id(e.g.,T-001),workstream(e.g.,WS-A),status, andupdatedtimestamps. - Status Transitions: The runtime validates that tasks cannot move to
doneunless the parentspecandplanare in anactivestate. - Dependency Gates: A task cannot transition to
startorcloseif its dependencies (listed independs_on) are not in thedonestatus.
Sources: src/cli/lib/project-state.js:124-140, src/cli/lib/project-state.js:460-475, test/package.test.js:315-330
Logic Flow for Status Rollups
When an action is taken on a Task (e.g., starting it), the system automatically promotes the parent Workstream and Project statuses.
The flow shows how a single task update triggers a ripple effect to ensure the overall project state reflects active work.
Sources: src/cli/lib/project-state.js:320-350, src/cli/commands/state.js:105-115
Artifact Scope & Directory Structure
The scope of Delano is strictly controlled via the assets/install-manifest.json, which defines the allowlist for files that constitute the runtime and project state.
Canonical Directories
.project/context/: Contains starter templates likeproject-brief.mdandsystem-patterns.md. These are considered "repo-owned" after installation..project/templates/: Storage for canonical artifact templates (task.md,spec.md, etc.) used by the CLI to scaffold new work..agents/schemas/: Houses the JSON schemas (e.g.,artifact-scope.json,evidence.schema.json) used for strict validation of project files.
Sources: assets/install-manifest.json:32-52, README.md:14-25, test/package.test.js:105-120
Scoped Validation Rules
Validation checks performed by .agents/scripts/pm/validate.sh include:
- Artifact Scope: Ensures all files in
.project/conform to the known artifact types. - Evidence Mapping: Verifies that tasks marked as
donecontain the required evidence entries in their Markdown body. - Path Safety: Ensures that artifacts do not leak absolute local paths, maintaining portability across different environments.
Sources: test/package.test.js:250-270, test/package.test.js:420-435, README.md:210-225
Conclusion
Artifact Schemas & Scope provide the foundational rigor required for agentic and human collaboration within Delano. By enforcing a strict schema for frontmatter and a logical hierarchy of files in the .project/ directory, the system ensures that the delivery state is always valid and traceable. This schema-backed approach allows the Delano CLI to automate status rollups and dependency checks, reducing manual overhead while maintaining high standards for evidence and quality.
Sources: README.md:20-25, src/cli/lib/project-state.js:750-760