Workflow Rules Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• .agents/rules/README.md
• .agents/rules/agent-coordination.md
• README.md
• AGENTS.md
• src/cli/lib/project-state.js
• src/cli/commands/state.js
• test/package.test.js

Workflow Rules Configuration in Delano defines the operational boundaries and state transition logic for an agent-agnostic delivery runtime. It ensures that planning, execution, and validation remain consistent across different coding agents and human operators by treating the .project/ directory as the immutable source of truth.

The configuration governs how artifacts such as specs, plans, and tasks transition between states (e.g., from planned to active or done). These rules are enforced through a combination of shared runtime assets in .agents/rules/, CLI-level validation logic, and file-backed delivery contracts.
Sources: README.md:10-18, AGENTS.md:14-22

Core Operating Model

The workflow follows a "Local Dossier" philosophy where every action must leave a traceable proof trail on disk. The rules mandate a specific hierarchy of files and directories to maintain project state.

Component	Responsibility
HANDBOOK.md	Canonical operating model and process definitions
.project/	Delivery source of truth: specs, plans, tasks, decisions
.agents/	Shared runtime: scripts, rules, hooks, and skills
AGENTS.md	First operational handoff for coding agents

Sources: README.md:20-28, AGENTS.md:1-8

Lifecycle State Transitions

The system enforces strict status rollups. When a task starts or closes, the parent workstream and project lifecycle (spec and plan) are automatically promoted to active. Conversely, a project or workstream can only be closed once all associated tasks have reached a terminal state.
Sources: src/cli/lib/project-state.js:388-410, src/cli/commands/state.js:107-111

This diagram illustrates the relationship between individual task transitions and the higher-level project or workstream status.
Sources: src/cli/lib/project-state.js:460-485, test/package.test.js:345-365

Automated Dependency Management

Workflow rules include logic to manage task blocking and unblocking based on dependency chains. When a task is marked as done, the system scans for dependent tasks that were blocked specifically by that dependency and automatically transitions them to ready.

Unblocking Logic

A task is automatically unblocked if:

1. Its current status is blocked.
2. The blocked_owner is classified as dependency, system, or auto.
3. All IDs listed in its depends_on frontmatter are now in done status.

Sources: src/cli/lib/project-state.js:425-450, test/cli.test.js:145-165

This sequence shows the automated transition of dependent tasks upon the completion of a prerequisite task.
Sources: src/cli/lib/project-state.js:412-423, test/cli.test.js:168-180

Validation Gates

The workflow configuration defines several "gates" that must be passed during the delano validate process. These are implemented as scripts within the .agents/scripts/ directory.

Mandatory Checks

• Artifact Schemas: Ensures .project files conform to JSON schemas for tasks, plans, and specs.
• Status Transitions: Rejects invalid state changes (e.g., moving to done while a parent workstream is still planned).
• Text Safety: Rejects files containing bidirectional (BIDI) control characters to prevent source-code injection.
• Evidence Mapping: Validates that terminal tasks (done) have recorded evidence for all acceptance criteria.

Sources: test/package.test.js:290-315, test/package.test.js:520-535, README.md:215-225

Agent Coordination and Leases

To support multi-agent environments, the configuration includes a lease-based coordination system. This prevents race conditions and conflicting edits by requiring agents to acquire an exclusive or shared lease before modifying specific project zones.

Lease Lifecycle

Leases include metadata such as owner, project, task, and zone. Releasing a lease requires a mandatory handoff summary to maintain the chain of provenance.
Sources: test/package.test.js:475-495, test/package.test.js:500-515

Option	Description
--owner	The agent or operator acquiring the lease
--zone	The file path or logical area being locked
--mode	Either exclusive or shared
--handoff	Required summary text provided upon release

Sources: test/package.test.js:503-512, src/cli/lib/install.js:60-70

Completion Rules

A workflow task is not considered complete based solely on code changes. The configuration mandates the following "Completion Rule":

1. Implementation or contract changes must be present.
2. Validation evidence must be recorded in the task's Evidence Log or update log.
3. The working tree state must be understood and reported.

Sources: AGENTS.md:28-32, src/cli/lib/project-state.js:145-155

Evidence Logging

Evidence is appended to markdown artifacts using the ## Evidence Log section. This is handled by the appendEvidence function which stamps the entry with an ISO8601 UTC timestamp.
Sources: src/cli/lib/project-state.js:175-185, src/cli/commands/state.js:335-345

// Example of evidence attachment logic in project-state.js
function appendEvidence(file, timestamp, text) {
  appendSectionEntry(file, "Evidence Log", `- ${timestamp}: ${cleanInlineText(text)}`);
}

Sources: src/cli/lib/project-state.js:176-178