From aa1bf207b9f2649a4f58a405f7669da4e7eba489 Mon Sep 17 00:00:00 2001
From: Amr Gharbeia <amr@gharbeia.net>
Date: Sun, 26 Apr 2026 12:14:08 -0400
Subject: [PATCH] Add AGENTS.md with literate programming workflow and tooling

- Documents the LP discipline: org files are source of truth
- Lists available tools: emacs --batch for tangle/eval/balance-check
- Documents the NEVER-edit-.lisp-directly rule
- Provides emergency recovery procedures

Scripts installed in ~/.opencode/bin/:
  - tangle: tangle org files via emacs --batch
  - org-eval: evaluate src blocks via emacs --batch
  - org-balance-check: check paren balance in org blocks
---
 AGENTS.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7107948
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,87 @@
+# Agent Guidelines for OpenCortex
+
+## Critical Rule: Literate Programming Discipline
+
+OpenCortex is a literate programming system. **All code lives in `.org` files.** The `.lisp` files in `library/gen/` and elsewhere are **generated build artifacts**.
+
+### NEVER edit `.lisp` files directly.
+
+If you edit a `.lisp` file directly:
+- Your changes will be overwritten on next tangle
+- The diff will be unreviewable  
+- You violate the single source of truth principle
+
+### ALWAYS edit `.org` files and regenerate.
+
+## Tools Available
+
+You have `emacs --batch` available. Use it for all org operations.
+
+### Tangling (Regenerating `.lisp` from `.org`)
+
+```bash
+# Tangle a single org file
+emacs --batch --load org --eval '(org-babel-tangle-file "path/to/file.org")'
+
+# Or use the convenience script
+~/.opencode/bin/tangle path/to/file.org
+```
+
+### Evaluating Src Blocks
+
+```bash
+# Evaluate all src blocks in an org file
+emacs --batch --load org --eval '(setq org-confirm-babel-evaluate nil)' --eval '(org-babel-execute-buffer)'
+
+# Or use the convenience script
+~/.opencode/bin/org-eval path/to/file.org
+```
+
+### Checking Paren Balance
+
+Before committing org changes, verify all lisp blocks have balanced parens:
+
+```bash
+~/.opencode/bin/org-balance-check path/to/file.org
+```
+
+## Workflow
+
+1. **Identify the org source** - Find which `.org` file contains the block you need to modify
+2. **Edit the org file** - Make changes in the `.org` file, not the `.lisp`
+3. **Evaluate the block** - Use `org-eval` to verify the block compiles
+4. **Tangle** - Use `tangle` to regenerate the `.lisp` file
+5. **Verify balance** - Use `org-balance-check` to ensure no paren mismatches
+6. **Test** - Load the system and run tests
+7. **Commit the org file** - The `.lisp` is a generated artifact; the org is what matters
+
+## Architecture Reminder
+
+- `skills/*.org` - Skill definitions (the source of truth)
+- `library/gen/*.lisp` - Generated from `skills/*.org` via tangle
+- `harness/*.org` - Core harness code (also org sources)
+- `library/*.lisp` - Generated from `harness/*.org` via tangle
+
+## Common Mistakes to Avoid
+
+1. **Editing `.lisp` directly** - This is the #1 mistake. Always fix org.
+2. **Forgetting to tangle** - Changes in org don't affect `.lisp` until you tangle.
+3. **Not evaluating blocks** - Use `C-c C-c` or `org-eval` to catch syntax errors early.
+4. **Assuming no Emacs** - `emacs --batch` works perfectly for all org operations.
+
+## Emergency: System Won't Load
+
+If the system fails to load due to a broken `.lisp` file:
+
+1. **Do not fix the `.lisp`**
+2. Find the corresponding `.org` file
+3. Fix the org source
+4. Tangle to regenerate
+5. If the org itself is broken, restore from git history and re-apply changes correctly
+
+## Test Command
+
+```bash
+cd /home/user/memex/projects/opencortex
+sbcl --non-interactive --load run-all-tests.lisp
+```