Agent-Agnostic Workflow
Relevant source files
The following files were used as context for generating this wiki page:
Delano is an agent-agnostic delivery runtime designed to decouple planning, execution, and validation from specific vendor workflows. It utilizes file-backed delivery contracts stored on disk, allowing multiple different coding agents (such as Claude, Codex, or Pi) and human operators to work from a shared operating model.
Sources: README.md:12-14, AGENTS.md:3
Shared Operating Model
The core of the agent-agnostic workflow is a "Local Dossier" approach where the source of truth resides within the repository itself rather than in a specific agent's memory or a cloud service. This model ensures that any agent entering the repository can immediately synchronize with the current project state.
Canonical Sources of Truth
The workflow relies on specific file paths to maintain state and provide instructions:
| Path | Role |
|---|---|
HANDBOOK.md | Canonical operating model and process rules. |
.project/ | File-backed delivery contracts (specs, plans, tasks, evidence). |
.agents/ | Shared runtime containing scripts, rules, and adapters. |
AGENTS.md | The primary operational handoff and shared workflow for all agents. |
Sources: README.md:16-22, AGENTS.md:12-19
First-Turn Workflow
Every coding agent is instructed to follow a specific sequence upon starting a task. This ensures that the agent understands the context and "contracts" before attempting any modifications.
The first-turn workflow prioritizes observation over action, requiring agents to validate project contracts and inspect files before changing them.
Sources: AGENTS.md:5-10, CODEX.md:5-7, PI.md:5-7
Adapter-Specific Entrypoints
To bridge the gap between different agent runtimes and the shared Delano core, the project uses a thin adapter layer. While the core logic remains shared in .agents/, specific entrypoint files provide the initial guidance for different agents.
- Codex: Uses
CODEX.mdto point to.agents/adapters/codex/README.md. - Pi: Uses
PI.mdto point to.agents/adapters/pi/README.md. - OpenCode: Uses
OPENCODE.mdto point to.agents/adapters/opencode/README.md. - Claude: Supported via compatibility mirrors in
.claude/which mirror.agents/.
Sources: CODEX.md:1-10, PI.md:1-10, OPENCODE.md:1-10, AGENTS.md:16-17
Lifecycle and State Transitions
The agent-agnostic workflow is enforced through automated state transitions. Agents interact with the system using CLI commands or by manually updating markdown frontmatter in .project/.
Task State Management
The system tracks the lifecycle of tasks and automatically rolls up status changes to parent workstreams and projects.
A task is not considered "done" until the implementation or contract change is present and validation evidence is recorded in the task or update log.
Sources: src/cli/lib/project-state.js:315-345, AGENTS.md:31-33
Onboarding and Safety
The delano onboarding command (driven by runOnboarding in src/cli/lib/onboarding.js) reviews the repository's AGENTS.md file against a standard rubric. It checks for:
- Mission: One-line purpose of the repo.
- Source-of-truth map: Compact list of trusted files.
- Approval Boundaries: Explicit rules for destructive or outbound actions.
- Verification Expectations: Instructions on how to report completion and run tests.
Sources: src/cli/lib/onboarding.js:100-145, AGENTS.md:36-42
Safety Boundaries
The workflow defines strict safety boundaries for all agents:
- No destructive actions or force-pushes unless explicitly requested.
- Logs must be privacy-safe and filtered for absolute local paths.
- Agent-specific behavior must remain in adapter folders, keeping the root entrypoints thin.
Sources: AGENTS.md:36-42
Summary
The Agent-Agnostic Workflow in Delano centralizes project intelligence into the repository's filesystem. By standardizing the "first-turn" behavior and providing a shared runtime (.agents/), Delano allows diverse AI tools to function as coherent contributors to a single, verifiable delivery stream.