AGENTS.md Apache-2.0 v0.1.1 runtime:none

Rootline

A route-aware AGENTS.md protocol for AI agents.
_{Read the route. Edit the work. Leave the receipt.}

How it works | How to use | Why different | Changelog | Contributing | Security | License | Credits

Contents

• How Rootline works
• How to use
• The Rootline primitives
• Why Rootline is different
• Compatibility notes
• Install checklist
• Changelog
• Contributing
• Security
• License
• Credits

How Rootline works

Rootline is a lightweight AGENTS.md protocol for AI agents.

Note

Rootline is only Markdown. No package. No daemon. No lock-in. The discipline is in the file.

It gives an agent a route through project instructions before the agent edits files, then asks for a route receipt after the edit. That makes the agent answer four questions every time:

Question	Rootline answer
What rules apply here?	Read the root doc and every child doc on the path to the work.
Where does local context live?	Keep durable guidance in the nearest local anchor.
When should docs change?	Update docs when structure, commands, ownership, workflow, or preferences change.
How do we know it followed the route?	Close with a Route Receipt.

flowchart TD
    A[Task] --> B[Find target paths]
    B --> C[Read root AGENTS.md]
    C --> D[Read child AGENTS.md files]
    D --> E[Edit precisely]
    E --> F[Update local anchors]
    F --> G[Run relevant checks]
    G --> H[Leave Route Receipt]

Loading

Tip

The core move is not "make more docs." The core move is "put the right rule near the place it governs."

---

How to use

Step 1 Copy AGENTS.md into the root of a project.

macOS / Linux

cp AGENTS.md /path/to/project/AGENTS.md

Windows PowerShell

Copy-Item .\AGENTS.md X:\path\to\project\AGENTS.md

Direct from GitHub

curl -fsSL https://raw.githubusercontent.com/AdrianParedez/rootline/v0.1.1/AGENTS.md -o /path/to/project/AGENTS.md

iwr https://raw.githubusercontent.com/AdrianParedez/rootline/v0.1.1/AGENTS.md -OutFile AGENTS.md

For a custom output path:

Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/AdrianParedez/rootline/v0.1.1/AGENTS.md" `
  -OutFile "X:\path\to\project\AGENTS.md"

Step 2 Ask an agent to install the project facts.

Install Rootline for this project.
Read the repository, keep AGENTS.md concise, and only add child docs where stable local guidance exists.

Step 3 Use the receipt on every meaningful change.

Rootline receipt:
- Route read: AGENTS.md
- Docs updated: AGENTS.md
- Checks run: reviewed headings and Route Map
- Gaps: no child docs exist yet

For an existing project

Ask the agent to inspect the repository first, then create only the docs that earn their keep:

Initialize Rootline in this existing project.
Create a root AGENTS.md.
Add child AGENTS.md files only for durable boundaries with distinct commands, ownership, or rules.
Leave a Rootline receipt listing what you read, created, skipped, and verified.

For a new project

Start with one root file. Let child docs appear only when the project develops real local rules:

• Add root AGENTS.md.
• Fill in project commands once they exist.
• Leave Operator Profile empty until durable preferences are known.
• Keep the Route Map honest.

---

The Rootline primitives

Primitive	What it does	Why it matters
Route Brief	States scope, route, local anchor, drift trigger, and receipt rule.	Prevents vague "read docs first" instructions.
Route Protocol	Defines how the agent finds and composes applicable instructions.	Makes routing explicit before any edit happens.
Local Anchor	Stores local facts near the files they govern.	Reduces root bloat and stale global rules.
Drift Control	Updates Rootline docs only when durable guidance changes.	Keeps docs current without turning them into task logs.
Route Receipt	Records route read, docs updated, checks run, and gaps.	Turns agent compliance into something reviewable.
Operator Profile	Starts empty, then captures durable operator/team preferences after install.	Keeps the starter universal without losing customisation.
Route Map	Lists known child instruction files.	Lets agents route quickly without pretending the map is proof.

Route Brief template

## Route Brief

- Scope:
- Route:
- Local anchor:
- Drift trigger:
- Receipt:

---

Why Rootline is different

Rootline is intentionally not just a self-documenting tree. It is a small operating pattern for agent accountability.

Pattern	Default behaviour
Plain AGENTS.md	Gives the agent repo instructions.
Self-documenting tree	Builds and maintains a hierarchy of AGENTS.md files.
Rootline	Builds a route, edits under that route, and leaves a receipt.

Rootline's unique stance:

• The Route Map is a guide, not proof.
• The Local Anchor owns local guidance.
• The root should stay thin.
• Child docs should earn their existence.
• Drift Control updates docs only when future work changes.
• Every meaningful edit ends with a Route Receipt.

Important

Rootline should make future work easier to route. If a new rule does not help a future agent decide what to read, where to edit, or how to verify, it probably does not belong in AGENTS.md.

---

Compatibility notes

Rootline is written in plain Markdown, so it can be read by any tool that can load repository instruction files.

Compatibility notes are informational. Check the linked tool documentation before publishing or changing tool-specific claims.

Tool	Rootline path
Codex	Uses AGENTS.md directly.
GitHub Copilot	Supports AGENTS.md files in the repository tree.
VS Code agent customizations	Can load AGENTS.md as always-on workspace instructions.
OpenCode	Uses AGENTS.md and can improve one through /init.
Claude Code	Use CLAUDE.md with @AGENTS.md, or a symlink where appropriate.

<!-- CLAUDE.md bridge -->
@AGENTS.md

_{Different tools load instruction files differently. Rootline stays portable by keeping the file plain, concise, and explicit.}

---

Install checklist

• Add root AGENTS.md.
• Fill in project commands that actually exist.
• Leave Operator Profile empty until durable preferences are known.
• Add child docs only where local rules differ.
• Update the Route Map when child docs are added, moved, or removed.
• Ask the agent to leave a Route Receipt after the first change.

---

Changelog

Current protocol version: 0.1.1.

See CHANGELOG.md for release notes.

---

Contributing

See CONTRIBUTING.md for contribution guidance.

---

Security

See SECURITY.md for security-sensitive reporting guidance.

---

License

Rootline is licensed under the Apache License, Version 2.0. See LICENSE.

---

Credits

Created by Adrian Paredez.

Rootline exists because AI agents do better when project context is close, current, and reviewable.¹

Footnotes

1. "Reviewable" means a human can see which route the agent read, what docs it updated, and what checks it ran. ↩