Amr Gharbeia
888ef00728
Submodule: function-calling API, json-alist-to-plist converter, tool-calls wiring in think(), diagnostics fix, version bump to 0.4.2. AGENTS.md: validate with emacs check-parens on org source (not SBCL).
52 lines
2.1 KiB
Markdown
52 lines
2.1 KiB
Markdown
# AGENTS.md
|
|
|
|
## Development Cycle (every change)
|
|
|
|
1. **Think in org** — write your reasoning, goals, and approach in the .org file first
|
|
2. **Write contract** — define a `** Contract` section listing each function's behavior:
|
|
`(fn-name args)`: description. Returns/guarantees ...
|
|
3. **TDD from contract** — each contract item becomes a `fiveam:test` in `* Test Suite`
|
|
a. 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
|
|
4. **Reflect in org** — once tests pass, ensure the implementation is in the .org source
|
|
5. **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
|
|
6. **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:
|
|
emacs --batch -Q --eval '(progn (find-file "org/FILE.org") (check-parens) (kill-buffer))'
|
|
|
|
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
|
|
- Before shipping a version, run the `** File Update Checklist` in `docs/ROADMAP.org`
|