Amr Gharbeia
01ff57096e
Submodule: 25 files changed — system-prompt-augment removal, 10 cognitive tools, vector count 9-10, README rewrite, ROADMAP updates, CONTRIBUTING rewrite, tangle normalization. AGENTS.md: rewritten compact (180-50 lines).
2.1 KiB
AGENTS.md
Development Cycle (every change)
- Think in org — write your reasoning, goals, and approach in the .org file first
- Write contract — define a
** Contractsection listing each function's behavior:(fn-name args): description. Returns/guarantees ... - TDD from contract — each contract item becomes a
fiveam:testin* Test Suitea. Write the test first → tangle → run → prove it FAILS (RED) b. Write the implementation → tangle → run → prove it PASSES (GREEN) c. Record both failure and success output - Reflect in org — once tests pass, ensure the implementation is in the .org source
- Update literate prose — write/update the explanatory text around the code: what it does, why it exists, how it connects to the rest of the system
- Commit — only when asked. Ask first.
Commands
Tangle a single file: emacs --batch --eval "(progn (require 'org) (find-file "org/FILE.org") (org-babel-tangle) (kill-buffer))"
Validate structural integrity: sbcl --noinform --eval '(with-open-file (f "lisp/FILE.lisp") (loop (read f nil (return))))' --quit
Run tests:
sbcl --noinform
--eval '(load (merge-pathnames "quicklisp/setup.lisp" (user-homedir-pathname)))'
--eval '(ql:quickload :passepartout :silent t)'
--eval '(load "lisp/FILE.lisp")'
--eval '(fiveam:run (intern "SUITE-NAME" :passepartout-TESTS))' --quit
For error details: bind fiveam:on-failure to :debug
REPL (port 9105) — preferred when available
Start: passepartout daemon
Send code:
msg = '(:type :event :payload (:sensor :repl-eval :code "(+ 1 2)"))'
s.sendall(f'{len(msg):06x}'.encode() + msg.encode())
When REPL is up: TDD in-image first, then reflect to .org and tangle. When REPL is down: fall back to the SBCL cycle above.
Rules
- .org is source of truth; .lisp is generated — never edit .lisp directly
- Every code change starts with a contract and a failing test
- Prove RED before writing implementation
- Validate before committing
- If a tool fails, explain why and ask before trying alternatives