adrlane

Documentation-as-code bootstrap for AI agents.

adrlane scaffolds a minimal docs/ layout and agent skills so AI tools know where to read and write project documentation. The agent decides when to update docs — there is no sync pipeline or enforcement.

Install

Global CLI (recommended)

Install adrlane once on your machine with uv:

uv tool install adrlane

From a local checkout:

uv tool install -e .

Verify:

adrlane --help

Development checkout

Clone the repository and install dependencies:

git clone https://github.com/koradon/adrlane.git
cd adrlane
uv sync
uv run adrlane --help

Quick start

Run these commands from your project repository root:

cd /path/to/your-project

# 1. Scaffold docs and install project-local agent skills
adrlane init

# Multi-repo workspace (project root is not a single git repo):
adrlane init --workspace   # adds .adrlane/workspace.yaml for doc routing
# Then run `adrlane init` in each sub-repository for service-level docs.

# 2. Optional: install skills globally (one copy for all projects)
adrlane skills install --global

Preview changes without writing files:

adrlane init --dry-run

Limit which agent adapters init installs:

adrlane init --agent cursor
adrlane init --agent cursor --agent claude-code

After upgrading the adrlane package, refresh skills:

adrlane skills upgrade --global
adrlane skills upgrade --local   # run from a bootstrapped repo

Commands

init and skills --local always use the current working directory — there is no --path flag. Change into the target repository first.

init never overwrites existing files, so re-running it after upgrading the adrlane package won't refresh stale docs/llm/* contract files. Run adrlane upgrade for that. It never touches user-owned content: docs/README.md, docs/ideas/README.md, docs/roadmap/README.md, the contents of docs/{specs,plans,adr,ideas,roadmap}, or .adrlane/workspace.yaml.

What init creates

init scaffolds a minimal core that grows with the project:

Templates live in docs/llm/templates/. Documents use markdown sections (## Status, ## Related) — not YAML frontmatter.

When the project gains new documentation needs (runbooks, API reference, CLI docs), the agent adds new folders under docs/ and updates docs/README.md. init does not predict project type.

Release history stays in Git and release tooling — not in docs/.

Agent skills

By default, init installs six skills for Cursor and Claude Code:

Project-local (default via init): .cursor/skills/ and .claude/skills/ in the repository.

Global (optional via skills install --global): same skills in your home directory, shared across all projects.

Skills are thin adapters; the canonical contract lives in docs/llm/AGENT_PROTOCOL.md and docs/llm/DECISION_RULES.md.

Multi-repo workspace

Use this when the Cursor workspace root is not a single git repository — for example a folder that contains several independent repos plus shared project docs.

Setup

cd /path/to/project-root

# Project-level docs + routing config + skills
adrlane init --workspace

# Service-level docs in each repository
cd repository1 && adrlane init
cd ../repository2 && adrlane init

Open the project root in Cursor so routing applies. Optionally install skills globally once: adrlane skills install --global.

Layouts

Flat — repositories are direct children of the project root. No repo_roots needed:

project/
  docs/                 ← cross-cutting ADRs, specs, roadmap
  repository1/docs/     ← service-specific docs
  repository2/docs/

Grouped — repositories live under category folders. Uncomment and edit repo_roots in .adrlane/workspace.yaml:

project/
  docs/
  services/order-service/docs/
  frontends/checkout-fe/docs/

project_docs: docs
repo_roots:
  - services
  - frontends

How routing works

The adrlane-workspace-routing skill (active when .adrlane/workspace.yaml exists) sends documentation to:

The other adrlane-write-* skills follow the resolved path automatically. Link project and service docs in ## Related.

Contributing

Run tests:

uv run pytest

Install pre-commit hooks:

uv run pre-commit install
uv run pre-commit run --all-files

Dependency management:

uv add <package>          # runtime dependency
uv add --dev <package>    # dev dependency
uv lock                   # refresh lockfile after manual pyproject edits

License

AGPL-3.0-or-later. See LICENSE.