62 lines
2.9 KiB
Org Mode
62 lines
2.9 KiB
Org Mode
#+TITLE: Contributing to Passepartout
|
|
#+AUTHOR: Passepartout Contributors
|
|
#+STARTUP: content
|
|
#+FILETAGS: :docs:contributing:
|
|
|
|
* Philosophy
|
|
Passepartout is built on a "Zero-Bloat" mandate. The core kernel is mathematically pure, pushing all peripheral logic, API integrations, and routing to hot-reloadable "Skills".
|
|
|
|
* TDD Discipline (Red-Green-Refactor)
|
|
|
|
All code changes MUST follow this cycle:
|
|
|
|
1. *Write a failing test* — capture the desired behavior as a FiveAM test
|
|
in a =* Test Suite= section within the relevant =.org= file
|
|
2. *Prove it fails* — run =sbcl --eval "(asdf:test-system :passepartout)"=
|
|
and confirm the new test fails (RED) before writing implementation
|
|
3. *Write the code* — modify the implementation in the same =.org= file
|
|
4. *Prove it passes* — run the test suite again, confirm GREEN
|
|
5. *Reflect* — ensure the test and code are both in the =.org= literate source
|
|
|
|
For *existing code* that lacks tests: write a characterization test that
|
|
captures current behavior as the spec. Then refactor.
|
|
|
|
No test may be committed without proof it was first run to failure.
|
|
|
|
* Literate Granularity
|
|
We strictly adhere to Literate Programming using Org-mode.
|
|
- *Never* edit `.lisp` files in `src/` directly.
|
|
- Modify the corresponding `.org` files in the `literate/` or `skills/` directories.
|
|
- Run `org-babel-tangle` to generate the source code.
|
|
- Every architectural decision, constraint, and implementation detail must be documented alongside the code in the `.org` file.
|
|
|
|
* Skill Creation Standard
|
|
Skills are the building blocks of Passepartout. They reside in the `skills/` directory.
|
|
|
|
A skill must define:
|
|
1. *Trigger*: A lambda determining if the skill should activate based on the context.
|
|
2. *Probabilistic Gate*: Optional. Generates a prompt for the LLM.
|
|
3. *Deterministic Gate*: A hardcoded Lisp function that guarantees safety or executes side-effects (the "Bouncer" pattern).
|
|
|
|
Example Registration:
|
|
#+begin_src lisp
|
|
(defskill :skill-example
|
|
:priority 100
|
|
:trigger (lambda (ctx) ...)
|
|
:probabilistic nil
|
|
:deterministic (lambda (action ctx) ...))
|
|
#+end_src
|
|
|
|
* The Unified Envelope (Communication Protocol)
|
|
All inter-process communication occurs via the Unified Envelope. Do not use legacy specific types like `:CHAT`.
|
|
- Always use semantic types: `:REQUEST`, `:EVENT`, `:RESPONSE`, `:STATUS`, `:LOG`.
|
|
- Include routing metadata in the `:META` block (e.g., `(:SOURCE :TUI)`).
|
|
- Ensure generated `:REQUEST` messages include a mandatory `:TARGET` field.
|
|
|
|
* Pull Request Process
|
|
1. Choose an Org file and write a failing test in its =* Test Suite= section.
|
|
2. Tangle and run to confirm RED (the test fails).
|
|
3. Write the implementation in the same Org file, tangle, run to confirm GREEN.
|
|
4. Ensure your working tree is clean.
|
|
5. Run the full test suite: =sbcl --eval "(asdf:test-system :passepartout)"=.
|
|
6. Submit a PR outlining the architectural intent and the specific Literate changes. |