ADR-001: Canonical Documentation and Agent Structure

Status

Accepted

Context

Switchain Services had documentation and agent customization spread across multiple locations with overlapping responsibilities.

• Conventions lived under ai-rules/.
• Claude, Copilot, and Cursor each referenced overlapping guidance in different formats.
• Some documentation references pointed to project-docs/, which did not exist as a real directory in the repository.
• Review workflows expected a docs/commands/ layer, but that layer was missing.

This created three problems:

1. The repository had no single canonical documentation tree.
2. Assistant-specific files could drift away from each other.
3. New contributors and agents had to infer which paths were authoritative.

At the same time, the nodo repository already demonstrated a cleaner model:

• canonical docs under docs/
• shared conventions under docs/conventions/
• durable decisions under docs/decisions/
• active plans under docs/development/
• a shared agent layer projected into tool-specific formats

Switchain Services needed the same structural clarity.

Decision

1. Canonical Documentation Lives Under docs/

The repository-wide documentation source of truth is the docs/ tree, rooted at Documentation Root.

The canonical structure is:

• docs/conventions/ for coding standards, architecture rules, and implementation patterns
• docs/commands/ for review workflow documentation
• docs/security/ for security investigations and incident analysis
• docs/decisions/ for durable ADR-style decisions
• docs/development/ for active plans, proposals, and exploratory technical work

The legacy ai-rules/ tree is retired and must not be reintroduced.

The non-existent project-docs/ path is also retired and must not be referenced again.

2. Canonical Shared Agent Definitions Live Under .agents/

The shared source of truth for agent and command definitions lives under .agents/.

The structure is:

• .agents/agents/ for shared agent definitions
• .agents/commands/ for shared command wrappers

Tool-specific folders are projections of that shared layer:

• .claude/ is the Claude-native projection
• .github/agents/ is the Copilot-native projection
• .cursor/.rules/ is the Cursor-native approximation layer for conventions and workflow discovery

Cursor is explicitly not modeled as if it supported true subagent parity.

3. Documentation Types Have Clear Ownership

Documentation types are separated by intent:

• Use Conventions for stable coding and architecture rules.
• Use Development for proposals, plans, rollout notes, and exploratory work.
• Use Decisions for durable architectural or organizational decisions.

When a development document stops being exploratory and becomes a durable repository decision, it should be promoted into docs/decisions/.

4. Repository Entry Points Must Reference the Canonical Tree

Repository-wide entry points must point to the canonical structure above.

This includes:

• AGENTS.md
• CLAUDE.md
• .github/copilot-instructions.md
• .cursor/.rules/*

These files may tailor behavior for a tool, but they do not define independent sources of truth.

Rationale

Why Not Keep ai-rules/ and project-docs/

Keeping multiple documentation roots would preserve the ambiguity that caused the migration in the first place.

• ai-rules/ duplicated what now belongs in docs/conventions/.
• project-docs/ was referenced but did not exist, which made the repository contract internally inconsistent.
• Parallel trees would keep discovery and maintenance costs high.

Why Not Keep Separate Sources of Truth Per Assistant

Letting Claude, Copilot, and Cursor each define their own version of the repository contract would create drift.

The same review workflow or convention could diverge across files, which is exactly what the shared .agents/ layer is meant to prevent.

Why Use docs/development/ and docs/decisions/

These categories separate exploratory work from durable choices.

That makes it easier to answer two different questions:

• What are we currently considering?
• What has already been decided?

Consequences

• New stable conventions must be added under docs/conventions/.
• New durable architectural decisions must be added under docs/decisions/ as numbered ADRs.
• New plans and exploratory proposals must be added under docs/development/ using descriptive kebab-case names.
• Shared agent logic must be updated in .agents/ first, then projected into tool-specific folders.
• Tool-specific files should stay thin and reference canonical docs whenever possible.
• Future repository cleanup should reject the reintroduction of ai-rules/ or project-docs/.

Deferred Scope

This ADR does not decide:

• automatic generation or synchronization between .agents/ and the tool-specific projections
• whether a shared skills layer should be introduced later
• a fuller taxonomy for additional documentation categories beyond the ones already created
• documentation automation for index generation or ADR scaffolding

Relation To Existing ADRs

This is the first ADR in switchain-services.