docs: restructure literate source into separate component files and remove legacy docs
This commit is contained in:
@@ -1,39 +0,0 @@
|
||||
#+TITLE: Phase 2: The Delegator (Roadmap)
|
||||
#+AUTHOR: org-agent
|
||||
#+DATE: [2026-03-23 Mon]
|
||||
|
||||
* Overview
|
||||
Phase 2 shifts focus from kernel architecture to capability expansion. Because the kernel (Phase 1) is a generalized Event Bus, **all Phase 2 features are implemented entirely as Org-Native Skills**. No modifications to the Lisp Core (`core.lisp`, `neuro.lisp`, `symbolic.lisp`) are required.
|
||||
|
||||
* The Phase 2 Skill Roster
|
||||
|
||||
** 1. The LLM Router
|
||||
- **Skill File:** `skills/skill-router.org`
|
||||
- **Role:** Meta-cognition. Replaces complex Lisp trigger logic with LLM intent classification.
|
||||
- **Trigger:** Catches general `:user-command` or ambiguous `:buffer-update` events.
|
||||
- **Action:** Instead of editing a file, it emits an internal Lisp event `(:type :EVENT :payload (:sensor :delegation :target-skill <skill-name>))`, forcing the engine to re-loop and trigger the specific skill.
|
||||
|
||||
** 2. Deep Memory (Vector/Semantic Search)
|
||||
- **Skill File:** `skills/skill-atomic-notes.org`
|
||||
- **Role:** Context augmentation beyond the live RAM `*object-store*`.
|
||||
- **System 2 (Lisp):** Wraps a local search tool (like `ripgrep` or a lightweight Lisp vector db).
|
||||
- **System 1 (LLM):** Formats the retrieved text into the Context API so downstream skills can read it before making decisions.
|
||||
|
||||
** 3. The Shell Actuator
|
||||
- **Skill File:** `skills/skill-shell-actuator.org`
|
||||
- **Role:** Gives the agent hands outside of Emacs.
|
||||
- **Registration:** Uses `(org-agent:register-actuator :shell #'execute-shell-safely)`.
|
||||
- **System 2 (Gatekeeper):** A massive, paranoid Lisp function that whitelist-checks commands (e.g., allows `git status`, blocks `rm`).
|
||||
|
||||
** 4. The Cron Scheduler
|
||||
- **Skill File:** `skills/skill-cron.org`
|
||||
- **Role:** Autonomous temporal action.
|
||||
- **Trigger:** `(eq sensor :heartbeat)`
|
||||
- **System 2 (Lisp):** Queries the `*object-store*` for deadlines. If a deadline has passed, it creates an action.
|
||||
- **System 1 (LLM):** Drafts a polite, contextual warning message to send to the user.
|
||||
|
||||
** 5. Web Research
|
||||
- **Skill File:** `skills/skill-web-research.org`
|
||||
- **Role:** Internet connectivity via headless text browsing.
|
||||
- **System 2 (Lisp):** Wraps `lynx` and `curl` to fetch webpage content.
|
||||
- **System 1 (LLM):** Parses the raw HTML/text and synthesizes a summary for the user.
|
||||
@@ -1,16 +0,0 @@
|
||||
#+TITLE: PRD: LLM Failover Cascade & Multi-Provider Support
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+STATUS: FROZEN
|
||||
|
||||
* 1. Purpose
|
||||
Ensure 100% availability of System 1 (Neural) reasoning via an ordered list of providers and automatic fallbacks.
|
||||
|
||||
* 2. Functional Requirements
|
||||
- **Backend Registry:** The core MUST allow Skills to register new AI providers (Gemini, OpenAI, Claude, etc.).
|
||||
- **Automatic Failover:** The `ask-neuro` function MUST iterate through a `*provider-cascade*` list, automatically trying the next provider if the previous one fails.
|
||||
- **Interactive Re-Ordering:** The system MUST allow the user to update the cascade order in real-time from Emacs.
|
||||
|
||||
* 3. Success Criteria
|
||||
- DONE Daemon correctly falls back from a failing API key to a working one.
|
||||
- DONE `M-x org-agent-set-model-cascade` successfully updates the live Lisp hierarchy.
|
||||
- DONE Support for 5+ providers (Gemini, OpenAI, Anthropic, OpenRouter, Ollama).
|
||||
@@ -1,17 +0,0 @@
|
||||
#+TITLE: PRD: Org-Native Multi-Modal Delivery
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+STATUS: FROZEN
|
||||
|
||||
* 1. Purpose
|
||||
Enable the agent to communicate outside of Emacs while maintaining all outbound records in a human-readable, homoiconic format.
|
||||
|
||||
* 2. Functional Requirements
|
||||
- **Org-Native Outbox:** The system MUST use a central Org file (`9_system/delivery.org`) as its outbound message queue.
|
||||
- **Actuator API:** A `:delivery` actuator MUST be registered to handle external messaging intents.
|
||||
- **Channel Support:** The system MUST support Signal, Telegram, and Discord metadata.
|
||||
- **Proactive Alerts:** The Cron skill MUST be able to route alerts to the delivery actuator based on Org properties.
|
||||
|
||||
* 3. Success Criteria
|
||||
- DONE New messages appear as structured headlines in `delivery.org`.
|
||||
- DONE Metadata (channel, target) is stored in native Org property drawers.
|
||||
- DONE No hidden JSON or external database required for queueing.
|
||||
@@ -1,17 +0,0 @@
|
||||
#+TITLE: PRD: Project Foundry (Scaffolding)
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+STATUS: FROZEN
|
||||
|
||||
* 1. Purpose
|
||||
Act as a senior engineer by autonomously scaffolding new project directories, git repos, and documentation templates.
|
||||
|
||||
* 2. Functional Requirements
|
||||
- **Directory Creation:** The system MUST be able to create new folders within the `$PROJECTS_DIR`.
|
||||
- **Git Integration:** The foundry MUST initialize a new git repository for every scaffolded project.
|
||||
- **Boilerplate Generation:** The system MUST write a customized `README.org` for new projects.
|
||||
- **GTD Connection:** The foundry MUST automatically add a `PROJ` headline to `gtd.org` with a dynamic `:PROJECT_PATH:`.
|
||||
|
||||
* 3. Success Criteria
|
||||
- DONE New projects appear in the physical filesystem and the GTD plan simultaneously.
|
||||
- DONE Path resolution handles environment variables (`$PROJECTS_DIR`) correctly.
|
||||
- DONE System 2 prevents overwriting existing project directories.
|
||||
@@ -1,16 +0,0 @@
|
||||
#+TITLE: PRD: The Skill Graph & Self-Awareness
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+STATUS: FROZEN
|
||||
|
||||
* 1. Purpose
|
||||
Enable recursive, networked intelligence by unifying logic (skills) and knowledge (Atomic Notes (Zettelkasten)).
|
||||
|
||||
* 2. Functional Requirements
|
||||
- **Dependency Tracking:** Skills MUST be able to declare dependencies on other skills via `#+DEPENDS_ON:`.
|
||||
- **Introspection:** The kernel MUST provide an API to list all active skills and read their source code.
|
||||
- **Topological Dispatch:** The system MUST resolve dependencies recursively before engaging a skill.
|
||||
|
||||
* 3. Success Criteria
|
||||
- DONE `(context-list-all-skills)` returns accurate priority and dependency metadata.
|
||||
- DONE Skills jailed in isolated packages can still resolve symbols from their declared dependencies.
|
||||
- DONE The Brain Mapper skill can successfully visualize the network.
|
||||
@@ -1,17 +0,0 @@
|
||||
#+TITLE: PRD: Kernel Web Dashboard
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+STATUS: FROZEN
|
||||
|
||||
* 1. Purpose
|
||||
Provide a read-only visual interface for monitoring the Lisp Machine's internal state and execution logs.
|
||||
|
||||
* 2. Functional Requirements
|
||||
- **Web Server:** A lightweight HTTP server (Hunchentoot) MUST run inside the kernel.
|
||||
- **Skill Visualization:** The dashboard MUST display the current Skill Graph, priorities, and jailing status.
|
||||
- **Log Monitoring:** The dashboard MUST display the most recent 20-50 system log entries.
|
||||
- **Remote Access:** The dashboard MUST be accessible from other computers on the local network (binding to 0.0.0.0).
|
||||
|
||||
* 3. Success Criteria
|
||||
- DONE Dashboard loads at `http://<ip>:8081`.
|
||||
- DONE Skill list updates dynamically as new skills are hot-loaded.
|
||||
- DONE Kernel errors are visible in the web UI.
|
||||
@@ -1,23 +0,0 @@
|
||||
#+TITLE: PRD: Skill-Based Dynamic Model Switching
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+DATE: 2026-03-24
|
||||
#+STARTUP: content
|
||||
|
||||
* Overview
|
||||
The `org-agent` currently relies on hardcoded LLM model strings within its pluggable provider skills. To match the flexibility of the legacy Openclaw system while maintaining a **Minimalist Core**, we will implement a "Homoiconic Configuration" model using the **Skill Graph**. Configuration settings will live as standard Org-mode properties in the user's memex, and a dedicated configuration skill will provide lookup services to other skills.
|
||||
|
||||
* Mandates
|
||||
- **The Org Mandate:** Configuration MUST be human-editable and machine-readable within `.org` files.
|
||||
- **Minimalist Core:** No new global variables or state-management registries shall be added to the kernel (`src/*.lisp`).
|
||||
- **Skill Graph Sovereignty:** Capabilities MUST build upon one another via dependencies.
|
||||
|
||||
* Requirements
|
||||
1. **Property-Based Configuration:** The system MUST allow defining LLM models via Org-mode properties (e.g., `:LLM_MODEL_OPENAI: gpt-4o`) anywhere in the loaded memex files.
|
||||
2. **Configuration Skill:** A new skill (`skill-environment-config.org`) MUST be created to handle property lookups within the persistent `*object-store*`.
|
||||
3. **Skill Integration:** Provider skills (OpenAI, Anthropic, OpenRouter) MUST declare a dependency on `skill-environment-config` and query it for their model string at runtime.
|
||||
4. **Late-Binding Updates:** Because the kernel updates the `*object-store*` on every buffer save, changing a model string in an Org file results in an immediate, hot-swapped change to the agent's behavior.
|
||||
|
||||
* Acceptance Criteria
|
||||
- A user can add `:LLM_MODEL_OPENAI: gpt-4o` to a "Settings" headline in their memex.
|
||||
- The OpenAI provider skill successfully fetches this value via the configuration skill.
|
||||
- No modifications are made to the core Lisp daemon files.
|
||||
@@ -1,22 +0,0 @@
|
||||
#+TITLE: PRD: Model Discovery
|
||||
#+AUTHOR: PSF Requirements Definer
|
||||
#+DATE: 2026-03-24
|
||||
#+STARTUP: content
|
||||
|
||||
* Overview
|
||||
Users currently lack visibility into the LLM models available via the registered provider skills (OpenAI, Anthropic, OpenRouter). To match Openclaw's UX while preserving a Minimalist Core, the system needs an intra-skill discovery protocol.
|
||||
|
||||
* Mandates
|
||||
- **The Org Mandate:** Outputs must be rendered natively in Org-mode buffers.
|
||||
- **Minimalist Core:** No state or new capabilities shall be added to the Lisp Daemon. All discovery logic must be localized to the Skill Graph.
|
||||
|
||||
* Requirements
|
||||
1. **Dynamic Provider Introspection:** The system MUST be able to query loaded skills dynamically to find which ones act as LLM providers.
|
||||
2. **Model Listing API:** Every provider skill MUST export a function that returns a list of its available models (e.g., ID, Context Window).
|
||||
3. **The Explorer Skill:** A new skill (`skill-model-explorer.org`) MUST intercept the command `@agent list models` and aggregate the results from all providers.
|
||||
4. **Org-Table Output:** The Explorer Skill MUST output the aggregated list back to the Emacs buffer formatted as an `org-table` for immediate human readability.
|
||||
|
||||
* Acceptance Criteria
|
||||
- Writing `@agent list models` in an Org buffer and saving triggers the Explorer Skill.
|
||||
- An Org-mode table is inserted below the command containing columns for `Provider`, `Model`, and `Context`.
|
||||
- Adding a new provider skill automatically includes its models in future queries without modifying the Explorer Skill.
|
||||
@@ -1,47 +0,0 @@
|
||||
#+TITLE: PROTOCOL: Skill-Based Configuration
|
||||
#+AUTHOR: PSF Architect
|
||||
#+DATE: 2026-03-24
|
||||
#+STARTUP: content
|
||||
|
||||
* Overview
|
||||
This protocol defines the skill-to-skill interface for retrieving environment configuration from the Org-mode Object-Store. It leverages the **Skill Graph** to provide a centralized configuration API for all other skills.
|
||||
|
||||
* The Configuration Skill (`skill-environment-config.org`)
|
||||
|
||||
** 1. Internal Logic
|
||||
The skill iterates over the kernel's `*object-store*` to find headlines containing specific properties.
|
||||
|
||||
#+begin_src lisp
|
||||
(defun get-config-attribute (property-key &optional default)
|
||||
"Searches the global *object-store* for any headline containing PROPERTY-KEY."
|
||||
(let ((store org-agent:*object-store*))
|
||||
(maphash (lambda (id obj)
|
||||
(declare (ignore id))
|
||||
(when (eq (org-agent:org-object-type obj) :HEADLINE)
|
||||
(let ((val (getf (org-agent:org-object-attributes obj) property-key)))
|
||||
(when val
|
||||
(return-from get-config-attribute val)))))
|
||||
store)
|
||||
default))
|
||||
#+end_src
|
||||
|
||||
* Skill Graph Integration
|
||||
|
||||
** 2. Dependency Declaration
|
||||
Other skills requiring configuration MUST declare a dependency on this skill.
|
||||
|
||||
#+begin_src org
|
||||
#+DEPENDS_ON: skill-environment-config
|
||||
#+end_src
|
||||
|
||||
** 3. Provider Integration Example
|
||||
Provider skills will invoke the config skill's API during the System 1 prompt generation.
|
||||
|
||||
#+begin_src lisp
|
||||
(let ((model (org-agent.skills.skill-environment-config:get-config-attribute :LLM_MODEL_OPENAI "gpt-4-turbo-preview")))
|
||||
;; ... use model in API call ...
|
||||
)
|
||||
#+end_src
|
||||
|
||||
* No Core Modifications Required
|
||||
This protocol adheres to the **Minimalist Core** mandate by implementing the entirety of the "Dynamic Model Switching" logic within the Skill Layer.
|
||||
@@ -1,51 +0,0 @@
|
||||
#+TITLE: PROTOCOL: Model Discovery
|
||||
#+AUTHOR: PSF Architect
|
||||
#+DATE: 2026-03-24
|
||||
#+STARTUP: content
|
||||
|
||||
* Overview
|
||||
This protocol defines the interfaces allowing the `org-agent` to dynamically introspect available models from any loaded provider skill, outputting the result to Emacs as an Org table.
|
||||
|
||||
* 1. The Provider Export Interface
|
||||
Every skill acting as a Neural Provider MUST export a function named `GET-AVAILABLE-MODELS`.
|
||||
|
||||
#+begin_src lisp
|
||||
;; Signature
|
||||
(get-available-models) -> list-of-plists
|
||||
|
||||
;; Return Format Example
|
||||
'((:id "gpt-4-turbo" :context "128k")
|
||||
(:id "gpt-4o" :context "128k"))
|
||||
#+end_src
|
||||
|
||||
* 2. The Model Explorer Skill (`skill-model-explorer.org`)
|
||||
|
||||
** Dynamic Introspection
|
||||
The explorer uses the kernel's `(org-agent:context-list-all-skills)` API to find all skills whose name starts with `skill-provider-`.
|
||||
|
||||
For each matching skill, it looks up the package:
|
||||
#+begin_src lisp
|
||||
(let* ((pkg (find-package (intern (string-upcase (format nil "ORG-AGENT.SKILLS.~a" skill-name)) :keyword)))
|
||||
(fn (when pkg (find-symbol "GET-AVAILABLE-MODELS" pkg))))
|
||||
(when (and fn (fboundp fn))
|
||||
(funcall fn)))
|
||||
#+end_src
|
||||
|
||||
** Org-Table Formatting
|
||||
The explorer aggregates the plists and formats them into an Org table string:
|
||||
#+begin_example
|
||||
| Provider | Model ID | Context |
|
||||
|----------+----------+---------|
|
||||
| OpenAI | gpt-4o | 128k |
|
||||
#+end_example
|
||||
|
||||
* 3. Emacs Actuator Command
|
||||
The explorer generates a System 2 `approved-action` that instructs the `:emacs` actuator to insert this text.
|
||||
|
||||
#+begin_src lisp
|
||||
'(:type :REQUEST
|
||||
:target :emacs
|
||||
:payload (:action :insert-text
|
||||
:text "| Provider | Model ID | Context |\n..."
|
||||
:position :after-trigger))
|
||||
#+end_src
|
||||
Reference in New Issue
Block a user