PM Shell Script Runtime
Relevant source files
The following files were used as context for generating this wiki page:
The PM Shell Script Runtime is the core execution layer of Delano, responsible for managing the delivery lifecycle of projects. It consists of a set of bash scripts located in .agents/scripts/pm/ that handle planning, status reporting, and validation of file-backed delivery contracts. While the delano CLI provides a Node.js wrapper for these operations, the shell scripts remain the underlying source of truth for repository-native project management.
Sources: README.md:124-129, AGENTS.md:18-24
Architecture and Command Execution
The runtime is designed to be agent-agnostic and relies on local dependencies such as bash, git, and python3. The system treats the .project/ directory as the primary source of truth for all delivery state, while the .agents/ directory houses the runtime logic.
Command Wrapping Logic
The delano CLI acts as a thin distribution layer that invokes the PM shell scripts. When a command like delano status is executed, the CLI resolves the path to the corresponding script within the .agents/scripts/pm/ directory and executes it as a child process.
The diagram shows how the Node.js CLI layer delegates project management operations to the underlying shell script runtime.
Sources: src/cli/index.js:23-38, README.md:36-41, README.md:195-201
Core PM Scripts
The runtime provides several key scripts that manage different aspects of the project lifecycle. These are categorized into status reporting, initialization, and validation.
Runtime Script Inventory
| Script Path | CLI Equivalent | Purpose |
|---|---|---|
.agents/scripts/pm/init.sh | delano init | Scaffolds a new delivery project with required contract files. |
.agents/scripts/pm/status.sh | delano status | Reports the current state of projects, workstreams, and tasks. |
.agents/scripts/pm/validate.sh | delano validate | Runs comprehensive checks on schemas, transitions, and evidence. |
.agents/scripts/pm/next.sh | delano next | Identifies the next available task based on dependencies. |
.agents/scripts/pm/research.sh | delano research | Creates intake files for project-related research. |
.agents/scripts/pm/import-spec-kit.sh | delano import-spec-kit | Imports external specifications into Delano contracts. |
Sources: assets/install-manifest.json:85-95, src/cli/index.js:23-38, README.md:143-150
Validation and State Gates
The v0.2 runtime upgrade introduced strict validation gates within validate.sh. These gates ensure that project transitions follow the canonical operating model defined in HANDBOOK.md.
Validation Flow
The validation runtime checks for:
- Schema Compliance: Ensures
.mdartifacts match JSON schemas in.agents/schemas/. - Status Transitions: Prevents invalid movements (e.g., closing a task when a project is still "planned").
- Evidence Mapping: Verifies that "done" tasks contain recorded evidence in their logs.
- Path Safety: Checks for leaked absolute paths in logs using
check-log-safety.sh.
The sequence shows the validation script orchestrating specialized JavaScript checkers to verify the integrity of project contracts.
Sources: README.md:214-224, assets/install-manifest.json:54-75, AGENTS.md:28-32
Project Lifecycle Logic
The runtime manages the "Dossier" state through frontmatter manipulation and evidence logging. Key operations include rolling up task statuses to workstreams and projects.
- Activation: Starting a task (e.g., via
delano task start) automatically promotes the parent workstream and project plan to "active". - Dependency Resolution: Closing a task triggers a check for dependent tasks. If a task was "blocked" only by that dependency, its status is updated to "ready".
- Completion: A project is only marked "complete" when all associated tasks are in a "closed" state (
done,deferred, orcanceled).
Sources: src/cli/lib/project-state.js:338-350, src/cli/lib/project-state.js:397-414, src/cli/lib/project-state.js:424-441
Conclusion
The PM Shell Script Runtime provides a robust, file-backed foundation for project delivery. By separating the execution logic (Bash/Python/Node) from the delivery state (Markdown/JSON in .project/), Delano ensures that project management remains portable, transparent, and verifiable across different agent environments and operator workflows.