Skills Execution Framework
Relevant source files
The following files were used as context for generating this wiki page:
The Skills Execution Framework in Delano is a shared runtime layer designed to provide agent-agnostic capabilities for project delivery. It acts as a bridge between high-level operating models (defined in HANDBOOK.md) and the low-level file-backed contracts stored in the .project/ directory. The framework provides structured scripts, rules, and "skills" that allow different coding agents and operators to perform consistent planning, execution, and validation tasks.
Sources: README.md:14-18, README.md:32-34, AGENTS.md:1-5
Framework Architecture
The framework is organized within the .agents/ directory, which serves as the shared runtime surface. It consists of several key components that work together to manage project state and provide operational guidance to agents.
Core Components
| Component | Path | Description |
|---|---|---|
| Skills | .agents/skills/ | Domain-specific logic modules (e.g., breakdown, research, planning) containing runbooks and templates. |
| Scripts | .agents/scripts/ | Execution-layer scripts (JavaScript and Bash) for auditing, validation, and maintenance. |
| Rules | .agents/rules/ | Operational constraints for coordination, path standards, and test execution. |
| Hooks | .agents/hooks/ | Lifecycle event triggers for session tracking and status logging. |
| Schemas | .agents/schemas/ | JSON schemas for artifacts like plans, tasks, and evidence logs. |
Sources: assets/install-manifest.json:28-144, README.md:33-34
Data Flow and Lifecycle
The framework operates on a "file-as-truth" model. Skills and scripts interact with the .project/ directory to read and write markdown-based contracts.
The diagram above shows how agents utilize skills and PM scripts to mutate project contracts, which are then passed through validation gates to ensure consistency.
Sources: README.md:20-22, AGENTS.md:7-14, src/cli/lib/project-state.js:100-110
Skill Inventory and Structures
Each skill is a self-contained directory containing a SKILL.md definition, a references/runbook.md, and a set of markdown templates. This structure ensures that both human operators and LLM-based agents follow the same procedural logic.
Primary Skills
- Discovery & Research: Used for clarifying requirements and exploring technical unknowns before mutation of specs.
- Planning & Breakdown: Responsible for defining workstreams and decomposing them into granular tasks.
- Execution: Handles the active implementation phase, providing templates for stream and blocker updates.
- Quality & Learning: Manages gate decisions, quality evidence, and project retrospectives.
Sources: assets/install-manifest.json:113-144, README.md:126-134
Skill Output Validation
The framework includes a specific validation mechanism for skill outputs. It utilizes "eval fixtures" to ensure that the output generated by agents (e.g., summaries, reports) meets the required schema and evidence standards.
Sources: test/package.test.js:342-346, assets/install-manifest.json:10-11
Execution Layer (PM Scripts)
The framework exposes a set of Bash scripts under .agents/scripts/pm/ that wrap the core JavaScript logic for project management. These scripts are the primary entry points for both the CLI and agents.
Key PM Operations
| Script | Purpose |
|---|---|
init.sh | Scaffolds a new project directory and initial markdown files. |
validate.sh | Runs a suite of checks against artifact schemas, status transitions, and dependencies. |
status.sh | Provides a summary of open projects, tasks, and workstreams. |
next.sh | Analyzes dependencies to recommend the next actionable task. |
research.sh | Creates intake files for technical research. |
Sources: README.md:144-152, src/cli/commands/state.js:18-20
Logic: Status Rollups
The framework implements automatic "rollups" where the status of a child artifact (Task) influences the status of parent artifacts (Workstream, Spec, Plan).
The sequence above illustrates how the applyTaskRollups function in the runtime handles state propagation across the artifact hierarchy.
Sources: src/cli/lib/project-state.js:345-365, src/cli/commands/state.js:106-111
State and Template Management
The framework relies on a library of templates located in .project/templates/. These are rendered using a replacement token system during project, workstream, or task creation.
Template Rendering Logic
The renderTemplate function performs string replacement on tokens like <project-name>, <ISO8601 UTC>, and <pending|skipped|completed>. This ensures metadata like timestamps and ownership are injected consistently.
Sources: src/cli/lib/project-state.js:68-75, src/cli/lib/project-state.js:182-205
Code Snippet: Task Creation from Template
// src/cli/lib/project-state.js:235-243
const text = renderTemplate(root, "task.md", {
"T-001": id,
"WS-A": workstreamId,
"<task-title>": name,
"<ISO8601 UTC>": timestamp,
"<story_id or none>": options.storyId || "none",
"<acceptance criteria ids or none>": formatHumanList(options.acceptanceCriteriaIds || []),
"<date>: <evidence>": `${timestamp}: Created from .project/templates/task.md by \`delano task add\`.`
});
Sources: src/cli/lib/project-state.js:235-243
Runtime Safety and Boundaries
The Skills Execution Framework enforces several safety boundaries to prevent destructive actions by agents:
- Privacy-Safe Logging: Logs are filtered to ensure raw prompts are opt-in and local absolute paths are not leaked.
- Lease Coordination: Multi-agent environments use a lease system (
lease-manager.mjs) to prevent conflicting writes to the same task or file zone. - Handoff Requirements: Releasing a lease requires a mandatory handoff summary to maintain context between operators.
Sources: AGENTS.md:36-40, test/package.test.js:283-300, test/package.test.js:311-318
The Skills Execution Framework provides a structured, verifiable environment for coding agents. By combining file-backed contracts with automated validation and skill-based guidance, it ensures that project delivery remains traceable and consistent across different tools and contributors.