dank/command-center
1
0
Fork 0
Code Issues 5 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: rebuild KB in OKF v0.1 with live-verified facts

Browse Source 
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center
knowledge base: concept files promoted to path identity, index listings
stripped of frontmatter, all wikilinks/relative links resolved, every
checkable claim verified against the live fleet (Dankserver = Ryzen 7
7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged.
kb-lint exits 0.
This commit is contained in:
Frank
2026-08-28 07:57:13 -07:00
parent 552d1ef8bf
commit 02883d3ed2
116 changed files with 13008 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
omp-docs/core/agents-md-format.md
+196
View File
@@ -0,0 +1,196 @@
---
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 |