---
type: reference
title: AGENTS.md Format Specification
description: Canonical structure and conventions for the system-level instruction file that governs agent behavior during configuration sessions.
tags:
  - agents-md
  - configuration
  - progressive-disclosure
  - core-contract
  - unverified
timestamp: 2026-01-15
---

# AGENTS.md Format Specification

This document defines the canonical structure and conventions for the `AGENTS.md` file located at `/home/dank/.pi/AGENTS.md`. It is the behavioral contract that tells the agent who it is, what context it is in, and what rules apply.

---

## Purpose

`AGENTS.md` is a **progressive disclosure instruction file**. It does not tell the agent how to configure a specific tool — it tells the agent how to behave while configuring tools. Think of it as the difference between a recipe and a cookbook. The recipe tells you what to do with eggplant. The cookbook tells you how to think about cooking.

---

## Structure

The file follows a strict top-to-bottom structure:

```
# Title — Context Label
## Context Declaration
## Your Role: Persona
## Progressive Disclosure (header)
---
### Layer N: <Title>
<Content>
---
### Layer N+1: <Title>
<Content>
---
## Summary
```

### Section Order (Mandatory)

| Order | Section | Description |
|-------|---------|-------------|
| 1 | `# Title — Context Label` | One-line title with context label in em-dash. Example: `AGENTS.md — System Configuration Mode` |
| 2 | `## Context Declaration` | Brief paragraph stating where the user is and what it means. Must mention the directory path. |
| 3 | `## Your Role: <Persona>` | Persona definition with bullet-point traits. Keep it tight — 4-6 bullets max. |
| 4 | `## Progressive Disclosure` | Intro paragraph explaining the layering model, followed by `---` separators between layers. |
| 5 | `### Layer N: <Title>` | Individual instruction layers (see Layer Conventions below). |
| 6 | `## Summary` | Compact table of all layers as quick-reference rows. |

---

## Layer Conventions

### Naming

- Layers are numbered sequentially starting from 1.
- Use decimal sub-numbers for inserted layers (for example, `Layer 1.5`) to preserve ordering when new layers are added between existing ones.
- Format: `### Layer N: <Descriptive Title>`
- Make the title a **command or principle**, not a topic name. Prefer:
  - `Verify Before You Commit — Deterministic Check First`
  - `The Mandatory Documentation Fetch Protocol`
  - NOT `Documentation`
  - NOT `Package Installation`

### Content Structure

Give each layer this content:

1. **Opening callout** (if the rule is critical): Bold `**This is non-negotiable.**` or `**MANDATORY:**` prefix.
2. **Definition**: What the rule/concept is. One paragraph, plain English.
3. **Workflow or steps**: Numbered lists for procedural instructions.
4. **Examples**: Code blocks, commands, or concrete scenarios.
5. **Scope**: When the rule applies (and when it does not).
6. **Common mistakes** (optional): `❌` prefixed anti-patterns.
7. **Correct behavior** (optional): `✅` prefixed patterns.

### Layer Ordering Principle

Layers are ordered by **priority and dependency**, not alphabetical:

1. **Context layers** first (who you are, where you are)
2. **Pre-flight / safety layers** next (verification, documentation checks)
3. **Domain-specific layers** after that (tool rules, package rules, etc.)
4. **Emergency / fallback layers** last

A layer that gates another layer must come before the layer it gates. (for example, "check docs exist" comes before "fetch docs if missing".)

---

## Summary Table Conventions

The `## Summary` section at the bottom is a **quick-reference table** that maps each layer to its action.

### Format

```markdown
## Summary

| Context | Action |
|---------|--------|
| <Short layer title> | **<One-line action>** — <Optional detail>. |
```

### Rules

- Every layer must have exactly one row in the summary.
- The **Context** column uses a short phrase (2-5 words) that maps to the layer title.
- The **Action** column starts with **bold** text for the core directive, followed by an em-dash and a brief elaboration.
- Critical failures get emphasized: `**CRITICAL FAILURE** — this violates the core protocol`.
- The table is the **only** place where failure conditions and severity are stated.
- Rows are ordered to match layer numbering.

---

## Section Formatting

### Code Blocks

- Use triple backtick code blocks for commands, scripts, and configuration examples.
- Specify the language for syntax highlighting: ````bash`, ````json`, ````text`.
- Include inline comments in code blocks explaining what is right vs. wrong.
- Use `# CORRECT` and `# WRONG` comment labels for contrast examples.

### Lists

- Use **numbered lists** for sequential steps (workflows, protocols).
- Use **bullet lists** for non-sequential attributes, traits, or considerations.
- Use `❌` and `✅` prefixed bullets for anti-patterns vs. correct patterns.

### Emphasis

- Use `**bold**` for critical directives and failure conditions.
- Use `**bold**` in the Summary table for the core action phrase.
- Use backticks for file paths, commands, and config keys.
- Use `>` blockquotes sparingly — reserved for ASCII workflow diagrams.

### ASCII Workflow Diagrams

For critical decision flows, use ASCII art inside blockquotes:

```
User Request → Check index.md → Docs exist? → YES: Proceed
                              ↓
                              NO: STOP → Fetch → Verify → Proceed
```

---

## Adding New Layers

When adding a new behavioral rule:

1. **Determine placement**: Where does this layer fit in the priority/dependency order?
2. **Assign a number**: If inserting between existing layers, use a decimal (for example, `Layer 2.5`). If appending, use the next integer.
3. **Write the layer** following the Content Structure conventions above.
4. **Add a summary row**: Insert a matching row in the Summary table at the correct position.
5. **Verify ordering**: Ensure the layer order matches the dependency chain (gating layers before gated layers).

---

## What NOT to Include

| Do Not | Why |
|--------|-----|
| Tool-specific configuration syntax | That belongs in `/docs/tools/<tool-name>/` |
| Long reference tables | Keep the Summary table concise; details belong in layer content |
| More than 10 layers | If you need more, the file is too big — consider splitting or consolidating |
| Narrative prose | Make every sentence actionable or declarative |
| Personal opinions or preferences | This is a system contract, not a blog post |

---

## File Metadata

| Property | Value |
|----------|-------|
| Path | `/home/dank/.pi/AGENTS.md` |
| Format | Markdown (GitHub Flavored) |
| Max layers | 10 (soft limit) |
| Max file size | ~15 KB (soft limit — if larger, consolidate) |
| Encoding | UTF-8 |
| Line endings | Unix (LF) |

---

## Revision History

| Version | Date | Change |
|---------|------|--------|
| 1.0 | 2026-07-09 | Initial specification — defines structure, layer conventions, summary format, and add/remove procedures |