Amr Gharbeia
94a8a0ab0b
Some checks failed
Deploy-Agent-V15-Stdin / JOB-V15-STDIN (push) Failing after 3s
- Folders: literate->harness, src->library, system->environment, scripts->interfaces. - Synchronized all :tangle paths and system definitions. - Hardened .gitignore for binary and log artifacts. - Consolidated all documentation into docs/.
1.9 KiB
1.9 KiB
Contributing to OpenCortex
- Philosophy
- Literate Granularity
- Skill Creation Standard
- The Unified Envelope (Communication Protocol)
- Pull Request Process
Philosophy
OpenCortex 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".
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 OpenCortex. They reside in the `skills/` directory.
A skill must define:
- Trigger: A lambda determining if the skill should activate based on the context.
- Probabilistic Gate: Optional. Generates a prompt for the LLM.
- Deterministic Gate: A hardcoded Lisp function that guarantees safety or executes side-effects (the "Bouncer" pattern).
Example Registration:
(defskill :skill-example
:priority 100
:trigger (lambda (ctx) ...)
:probabilistic nil
:deterministic (lambda (action ctx) ...))The Unified Envelope (Communication Protocol)
All inter-process communication occurs via the Unified Envelope.
- 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
- Ensure your working tree is clean.
- Write tests for your skill in `tests/`.
- Tangle all files.
- Run the test suite: `sbcl –eval "(asdf:test-system :opencortex)"`.
- Submit a PR outlining the architectural intent and the specific Literate changes.