Claude Compatibility Mirror
Relevant source files
The following files were used as context for generating this wiki page:
The Claude Compatibility Mirror is a structural convention within the Delano ecosystem designed to support coding agents that expect a specific .claude/ directory structure for their runtime. While Delano uses .agents/ as its canonical runtime directory, the mirror ensures that Claude-style paths remain functional without duplicating project logic or scripts.
The mirror serves as a bridge, allowing the project to remain agent-agnostic while specifically accommodating the path expectations of the Claude adapter. It ensures that any agent hardcoded to look for rules, hooks, or skills within .claude/ can seamlessly access the shared Delano runtime assets.
Sources: CLAUDE.md:1-8, README.md:52-52, AGENTS.md:18-18
Architectural Overview
The architecture of the compatibility mirror relies on a symbolic link (or a fallback directory copy) that points from .claude/ to the canonical .agents/ directory. This approach maintains a single source of truth for the runtime while providing multiple access paths.
Component Relationship
The diagram shows the relationship where .claude/ acts as a pointer or mirror to the primary .agents/ directory.
Sources: assets/templates/context/project-structure.md:10-14, AGENTS.md:13-19, install-delano.sh:317-340
Mirror Implementation and Lifecycle
The mirror is established during the repository installation or bootstrap process. The system prefers using symbolic links to avoid data duplication and "split-brain" scenarios where different agents see different versions of the runtime.
Installation Logic
During installation, the install-delano.sh script (the legacy bridge installer) performs specific checks to ensure the mirror is correctly configured:
- Symlink Verification: It checks if
.claudealready exists as a symlink and verifies if it points to.agents. - Conflict Resolution: If
.claudeexists as a directory or points elsewhere, the installer offers to replace it (or forces replacement if the--forceflag is used). - Fallback Mechanism: If the operating system or environment does not support symbolic links, the installer falls back to an
a -cp(archive copy) of the.agentsdirectory to.claude.
| Mechanism | Priority | Description |
|---|---|---|
| Symbolic Link | Primary | ln -s .agents .claude creates a pointer that consumes no extra space. |
| Directory Copy | Fallback | Used only if symlink creation fails; duplicates files into .claude/. |
Sources: install-delano.sh:317-340, test/cli.test.js:462-466
Operational Usage for Agents
Agents interacting with the Delano repository follow a specific hierarchy for discovering their operating instructions and runtime scripts.
First-Turn Workflow for Claude
When an agent starts a session, it is instructed to follow these steps:
- Read
AGENTS.mdfor the shared workflow and source-of-truth map. - Read
.agents/adapters/claude/README.mdfor Claude-specific technical notes. - Utilize
.agents/as the canonical runtime, acknowledging that.claude/is only a mirror.
Entrypoints
The repository contains several entrypoint files that guide different agents toward the shared runtime:
CLAUDE.md: The specific entrypoint for Claude. It is intentionally kept thin, directing the agent to the shared rules inAGENTS.mdand the mirrored runtime..claude/: Used by agents that expect this specific path standard for rules or tool discovery.
Sources: CLAUDE.md:1-8, AGENTS.md:5-11, CODEX.md:1-10
Integration with Delano CLI
The @bvdm/delano CLI manages the installation of the mirror as part of its agent-runtime category. The CLI ensures that when the runtime is updated, the compatibility layer remains intact.
This sequence shows how the CLI establishes the mirror and how the agent transparently accesses canonical files through the mirrored path.
Sources: src/cli/lib/install.js:25-30, README.md:144-162, test/cli.test.js:335-338
Summary
The Claude Compatibility Mirror is a vital part of Delano's agent-agnostic posture. By providing a mirrored path at .claude/, Delano satisfies specific agent requirements while maintaining the integrity of its single source of truth within the .agents/ directory. This ensures that all scripts, hooks, and skills are shared across all supported adapters (Claude, Codex, OpenCode, and Pi) without duplication.
Sources: README.md:52-52, CLAUDE.md:7-8, AGENTS.md:18-18