adrlane

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

1. Install the CLI globally (see Install).
2. From your project repository root, scaffold docs and project-local skills:

cd /path/to/your-project
adrlane init

3. Optional: install skills once for all projects on this machine:

adrlane skills install --global

4. Work with your agent as usual. When docs should change, the agent uses the installed skills (see Agent workflow).

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.

Preview without writing files:

adrlane init --dry-run

Limit which agent adapters init installs:

adrlane init --agent cursor
adrlane init --agent cursor --agent claude-code
adrlane init --agent codex
adrlane init --agent agy

init and skills --local always use the current working directory — there is no --path flag.

Upgrading

init is additive: it never overwrites an existing file. After you upgrade the adrlane package, re-running init will not refresh stale docs/llm/* contracts or skills. Use upgrade for that.

# 1. Upgrade the installed CLI
uv tool upgrade adrlane

# 2. In each bootstrapped repository: refresh package-owned content
cd /path/to/your-project
adrlane upgrade

# 3. If you use global skills, refresh those too
adrlane skills upgrade --global

adrlane upgrade overwrites:

• docs/llm/* contract files and templates
• .adrlane/bootstrap-version
• local agent skill files (same as skills upgrade --local)

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.

Preview: adrlane upgrade --dry-run. Details: ADR 0005.

Commands

Agent workflow

adrlane does not detect documentation gaps, schedule updates, or write docs on its own. The agent decides when documentation needs updating during normal development.

Typical loop:

1. Developer installs adrlane and runs adrlane init once per repository.
2. Developer works with Cursor or Claude Code as usual.
3. When the agent judges that behavior, decisions, or structure should be recorded, it uses the installed skills and docs/llm/* to create or patch files under docs/.
4. Developer reviews with git diff and commits normally.

Skills are thin adapters; the contract is docs/llm/AGENT_PROTOCOL.md and docs/llm/DECISION_RULES.md.

Documentation model

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.

One exception grows outside that minimal core on request rather than by default: the adrlane-write-architecture-overview skill creates or refreshes a single docs/architecture.md — a whole-system overview with diagrams — when asked, or proactively after a change that alters module boundaries, execution flow, or requirements to run.

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

Agent skills

By default, init installs seven skills for every supported agent:

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

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

Codex CLI scans both: <repo>/.codex/skills as a project-local skill root, and $CODEX_HOME/skills (default ~/.codex/skills) as the user-level one. The same .codex/skills prefix therefore serves both scopes.

Antigravity CLI (agy) scans <workspace>/.agents/skills as its project-local skill root, but a different, unrelated global root: ~/.gemini/config/skills. Its adapter installs into .agents/skills for --local and .gemini/config/skills for --global — see ADR 0009.

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.