command-center/omp-docs/core/agents-md-format.md

type, title, description, tags, timestamp

type	title	description	tags	timestamp
reference	AGENTS.md Format Specification	Canonical structure and conventions for the system-level instruction file that governs agent behavior during configuration sessions.	agents-md configuration progressive-disclosure core-contract unverified	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

## 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