passepartout/AGENTS.md

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)

# 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

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

~/.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

cd /home/user/memex/projects/opencortex
sbcl --non-interactive --load run-all-tests.lisp