P7.MRD.003 — ADR directory exists for agent-tool repositories

Field	Value
Principle	P7 (Machine-readability)
Pack	agent-tool
Severity	warn
Evidence	strong
Stability	experimental

What it checks

The repository has a cmd/ directory with source files (signal of a CLI binary) but no docs/adr/ directory exists.

Why it matters

When an agent is asked to refactor an agent-facing tool, it needs to know which decisions are load-bearing vs. accidents of history. ADRs (Architecture Decision Records) are the canonical way to pin those decisions in machine-readable form.

How to fix

1. Create docs/adr/.
2. Add 0001-architecture-overview.md describing the top-level design choices.
3. Use YAML frontmatter (id, title, status, date, tags) so ADRs are parseable.

Template

---
id: 0001
title: Architecture overview
status: accepted
date: 2026-04-24
tags: [architecture, foundation]
---

# ADR 0001 — Architecture overview

## Context

<what drove the decision>

## Decision

<what we decided>

## Consequences

<positive and negative>

See also

• archfit's own docs/adr/0001-architecture-overview.md as a template.