Amr Gharbeia
aa1bf207b9
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 6s
- 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
88 lines
2.8 KiB
Markdown
88 lines
2.8 KiB
Markdown
# 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
|
|
```
|