Onboarding & Project Initialization
Relevant source files
The following files were used as context for generating this wiki page:
Onboarding and Project Initialization in Delano constitute the primary workflow for establishing file-backed delivery contracts within a repository. This process ensures that both human operators and coding agents align with the canonical operating model defined in HANDBOOK.md and the delivery source of truth located in the .project/ directory.
The system is designed to be "agent-agnostic," providing a shared runtime (.agents/) and explicit instructions via AGENTS.md to facilitate collaboration across different vendor workflows. The onboarding phase focuses on analyzing existing agent instructions, while initialization involves scaffolding the necessary directory structures and markdown-based contracts for project execution.
Sources: README.md:10-18, README.md:154-159, AGENTS.md:1-5
Agent Onboarding Workflow
The delano onboarding command is the recommended first step after installing the Delano runtime. Its primary purpose is to review the repository's AGENTS.md file against a packaged onboarding skill rubric to ensure coding agents have sufficient guidance for first-turn workflows and safety boundaries.
Analysis Process
The onboarding system performs a non-destructive analysis. It searches upward from a target directory for an AGENTS.md file and evaluates its content based on several key criteria:
- Mission Statement: Verification of core repository operating surface mapping.
- First-turn Workflow: Presence of numbered sequences for inspection and verification.
- Source-of-Truth Map: Explicit pointers to
HANDBOOK.mdand.project/. - Safety Boundaries: Documentation of approval requirements for destructive or public actions.
The following sequence diagram illustrates the approval-first logic of the onboarding command:
The onboarding logic strictly requires explicit approval before performing analysis, either through an interactive TTY prompt or the --approve-agents-analysis flag.
Sources: src/cli/lib/onboarding.js:98-154, src/cli/lib/onboarding.js:189-214, src/cli/commands/onboarding.js:3-14
Onboarding Rubric Components
| Rubric Label | Requirement | Description |
|---|---|---|
| Mission | Required | Maps the repo's core purpose and quality bar. |
| First-turn Workflow | Required | Numbered steps for initial agent orientation. |
| Source-of-truth Map | Required | Points to canonical files like HANDBOOK.md. |
| Safety Boundaries | Required | Explicitly states approval requirements for destructive actions. |
| Verification | Required | Instructions on how to report "done" or "blocked" status. |
| Sources: src/cli/lib/onboarding.js:101-143 |
Project Initialization & Scaffolding
Once a repository is onboarded, the delano init (via wrapper) or delano project create commands are used to initialize specific delivery projects. This process creates the physical infrastructure for the "Local Dossier" design posture.
Directory Structure Generation
Initialization creates a standardized hierarchy under .project/projects/<slug>/:
spec.md: The technical and product specification.plan.md: The delivery plan and risk assessment.decisions.md: An architecture and process decision log.tasks/: Directory for individual task contracts.workstreams/: Directory for grouping related tasks.updates/: Directory for progress and evidence logs.
Sources: src/cli/lib/project-state.js:186-200, README.md:21-29
Template Rendering Logic
Initialization relies on the renderTemplate function, which retrieves base templates from .project/templates/ and performs token replacement for metadata like project names, owners, and ISO8601 timestamps.
Core Initialization Commands
The CLI provides specific commands to transition from a bare repository to a fully initialized project state.
| Command | Purpose | Key Parameters |
|---|---|---|
delano install | Bootstraps the runtime | --target, --yes, --no-project-state |
delano project create | Scaffolds a new project | <slug>, --name, --owner, --outcome |
delano workstream add | Adds a task group | <project>, <id>, --name |
delano task add | Creates a task contract | <project>, <id>, --workstream, --depends-on |
| Sources: src/cli/index.js:132-154, src/cli/lib/project-state.js:154-159, src/cli/lib/project-state.js:220-225 |
Implementation Example: Project Creation
// src/cli/lib/project-state.js:160-205
function createProjectFromTemplates(root, options) {
const slug = requireSlug(options.slug, "project slug");
const targetDir = projectDir(root, slug);
// Scaffolding directories
mkdirSync(path.join(targetDir, "tasks"), { recursive: true });
mkdirSync(path.join(targetDir, "workstreams"), { recursive: true });
// Rendering core artifacts
const spec = renderTemplate(root, "spec.md", { ...baseReplacements });
writeFileSync(path.join(targetDir, "spec.md"), spec, "utf8");
}
Sources: src/cli/lib/project-state.js:160-205
Summary
Onboarding and initialization are the foundational steps for Delano's file-backed delivery model. Onboarding ensures that agent instructions in AGENTS.md meet quality and safety standards, while initialization transforms these standards into actionable project structures. By utilizing template-backed scaffolding, the system maintains consistency across different projects while preserving the "quiet, document-like" operational posture of the repository.
Sources: README.md:154-165, AGENTS.md:31-35