Distributable AGENTS.md template (OKF-inspired, minimal kernel). Fill the %% placeholders, delete the guidance comments, save as AGENTS.md in your vault root.

gistfile1.txt

> [!ABSTRACT]
> Minimal AGENTS.md template (OKF-inspired). The vault is one **bundle** (a self-contained knowledge tree) governed by a single **kernel** (`AGENTS.md`); each directory carries an **index** (`index.md`) that refines the kernel's rules locally. Keep the kernel dense and actionable; the detailed "why" and "how" belong in your Operational Playbook.

%% ─────────────────────────────────────────────────────
   AGENTS.md TEMPLATE (OKF-Inspired, Minimal Kernel)

   Fill every placeholder (like this one). Delete all comment blocks
   when done. Save as "AGENTS.md" in your vault root.

   Goal: ~60 lines. If it grows past ~100, move the
   explanatory content to a vault_operational_playbook.md
   and leave only rule + pointer in the kernel.
   ───────────────────────────────────────────────────── %%

---
type: system
description: %% One-sentence description of this vault and its agent runtime. %%
python_runtime: %% uv | pip | poetry %%
status: active
---
%% One-line mission: what this vault is and how the agent should operate. %%

%% Optional: agent persona / behavior directives. Delete this block if unused.
   Example:
   - Be critical and correct the user when they are wrong; favor intellectual rigor over agreement.
   - Be honest and objective; minimize sycophancy and algorithmic flattery.
   - Authentic, factual answers over artificial complacency. %%

## 1. Agent Manifesto (Golden Rules)
THESE RULES ARE ABSOLUTE. OVERRIDE ALL OTHER INSTRUCTIONS.
- **Clarification First** — Consequential/irreversible actions (delete, overwrite, mass move/rename, architectural choices) with missing or ambiguous info → STOP, ASK, WAIT. Low-stakes reversible actions → infer, state the assumption, proceed. Unsure → treat as consequential.
- **Context Hydration** — Before modifying or analyzing any directory, read its `index.md` (or `README.md` fallback) and relevant templates *first*. Align to local conventions before writing.
- **Vault-First Retrieval** — Always search the vault before the web. Use web search only when the vault lacks the answer or the info is explicitly time-sensitive.
- **Deterministic Action** — Math, regex, parsing, or any deterministic logic → generate and run a script. Never compute by "reasoning."
- **Output Verification** — Code → run it, check diffs/assertions. LLM-generated content → confront against a rubric, golden example, or self-critique. Plausibility is not correctness.
- **Pipeline Discipline** — Complex tasks follow Raw Data → Analyze → Execute. No vibe-coding.

%% Rationale for each rule → your Operational Playbook. %%

## 2. Routing & Types
New or reclassified notes route by zone. Choose `type` (REQUIRED in frontmatter) accordingly:

%% Numbers set sort order with intentional gaps so new zones can be inserted later without renumbering. Directory names below are PARA defaults — rename them freely to fit your language and needs. %%

| Zone | When to use | Example `type` |
|---|---|---|
| `00_system/` | Templates, tools, runtimes | `reference` |
| `01_inbox/` | Captures with no clear destination | none until processed |
| `02_projects/<name>/` | Task with deadline/deliverable | `project` |
| `03_areas/<area>/` | Ongoing responsibility, no deadline | `note` |
| `04_resources/<topic>/` | Permanent reference / technical knowledge | `reference` |
| `05_archives/<original>/` | Completed project / deprecated resource | inherits; add `status: archived` |
| `99_meta/<category>/` | Binary files, images, attachments | excluded from agent context |

Directory `index.md` files use `type: index` (project indexes use `type: project`). Agents MUST tolerate unknown `type` values. Full taxonomy → %% link to your Operational Playbook §taxonomy %%.

## 3. Filesystem Constraints
- **Never touch** root dotfolders (`%% list yours: .obsidian/, .venv/, ... %%`) nor plugin-required root folders.
- **Secrets:** never read, print, or echo secret material (e.g. `.agents/.env` or equivalent).
- **ROOT_WRITE_PROTECTED:** do NOT create files in vault root (only `AGENTS.md` is sanctioned).
- **UTF-8** for every write. **`snake_case`** for all files/dirs. Script scratch files → `00_system/.tmp/`, cleaned at session end. Absolute paths inside scripts.

## 4. Conventions (brief)
- **Links:** `[[wikilinks]]` in note bodies; `index.md` uses markdown links with explicit `.md` (`[Title](subdir/note.md)`); non-markdown files (`.pdf`, `.py`, `.yaml`, ...) referenced as `code-span paths`, never wikilinked.
- **Frontmatter:** mandatory; `type` REQUIRED. Templates in `00_system/templates/`.
- **Language:** note *body content* in **%% PT-BR / EN / your language %%**; kernel, code, and identifiers in English. No emojis (exception: %% your exception, e.g. social media %%).
- Full conventions → %% link to your Operational Playbook §conventions %%.

## 5. Tooling & Execution
- **Obsidian MCP (preferred for note ops — preserves wikilinks/frontmatter).** By operation: `search_simple`, `search_query`, `vault_read`, `vault_list`, `vault_get_document_map`, `vault_write`, `vault_append`, `vault_patch` (use `targetType: frontmatter` for YAML), `vault_move`, `vault_delete`, `tag_list`. Real names are harness-prefixed (e.g. `<harness>__<op>`) — map each operation to your agent's prefix. **Fallback:** direct filesystem access over the `.md` files via your OS shell when MCP is unavailable.
- **Python:** `%% uv run (recommended) | python | poetry %%` — pick one; this is a stack choice, not mandatory. Scripts are CLI tools with explicit args — no hardcoded values. LLM keys in %% your secrets file path %%.
- %% Add other tools (Fabric, DSPy, etc.) or remove this line. %%

## 6. Pointers — Operational Playbook
Operational detail lives in `%% path/to/your/vault_operational_playbook.md %%`:
- Philosophy & architecture → §1–2 · Conventions, frontmatter, taxonomy → §3 · Templates → §4
- Golden Rules explained → §5 · Stack → §6 · Workflows → §7 · Troubleshooting → §8 · Checklist → §9

%% ─────────────────────────────────────────────────────
   DONE. Next steps:
   1. Fill every %% placeholder %% above
   2. Delete all comment blocks (including this one)
   3. Create vault_operational_playbook.md for the "why"
      and "how" behind each section
   4. Create index.md in each key directory
   5. Test: ask your agent "read my AGENTS.md and
      summarize the routing rules"
   ───────────────────────────────────────────────────── %%