amr/org-agent-contrib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initial seed of domain-specific contrib skills

Browse Source
This commit is contained in:
Amr Gharbeia
2026-04-09 15:18:19 -04:00
commit 54e287788d
29 changed files with 2582 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
org-skill-architect.org Normal file
View File

@@ -0,0 +1,136 @@
:PROPERTIES:
:ID: cb3669d7-753b-41b6-9046-2141ffbb7254
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Architect Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :architect:blueprint:design:psf:
* Overview
The *Architect Agent* transforms a FROZEN PRD (Demand) into a rigorous PROTOCOL (Blueprint). It bridges the gap between high-level requirements and technical implementation.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Automate the technical design phase of the PSF project lifecycle.
** 2. User Needs
- *Perception:* Scan the Memex for FROZEN PRDs.
- *Synthesis:* Generate Lisp-idiomatic technical interfaces.
- *Actuation:* Autonomously append Phase B (Blueprint) to master notes.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Interfaces for blueprint actuation and requirement perception. Source of truth is the project's PRD.
** 2. Semantic Interfaces
"Checks if a project has a FROZEN PRD."
"Physically writes the PROTOCOL.org file."
* Phase D: Build (Implementation)
** PRD Perception
#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp
(defun architect-perceive-frozen-prd (note-path)
"Checks if a master note has a FROZEN PRD and lacks a Phase B section."
(let ((content (uiop:read-file-string note-path)))
(when (and (search "* Phase A: Demand (PRD)" content)
(search ":STATUS: FROZEN" content)
(not (search "* Phase B: Blueprint (PROTOCOL)" content)))
`(:note-path ,note-path :content ,content))))
#+end_src
** Note Scanning
#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp
(defun architect-scan-all-notes ()
"Scans all org-skill-*.org notes for demands ready for blueprinting.
Uses manual filtering to ensure robustness across Lisp environments."
(let* ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "/home/user/memex/notes/"))
(files (uiop:directory-files (uiop:ensure-directory-pathname notes-dir)))
(ready-notes '()))
(dolist (file files)
(let ((name (pathname-name file))
(type (pathname-type file)))
(when (and name type
(uiop:string-prefix-p "org-skill-" name)
(string-equal type "org"))
(let ((status (architect-perceive-frozen-prd file)))
(when status (push status ready-notes))))))
ready-notes))
#+end_src
** Cognitive Trigger
#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp
(defun trigger-skill-architect (context)
"Triggers on heartbeat if any master note is in a FROZEN PRD state."
(let ((type (getf context :type))
(payload (getf context :payload)))
(when (and (eq type :EVENT) (eq (getf payload :sensor) :heartbeat))
(let ((ready (architect-scan-all-notes)))
(when ready
(setf (getf (getf context :payload) :ready-notes) ready)
t)))))
#+end_src
** Neuro-Cognitive Prompt
#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp
(defun neuro-skill-architect (context)
(let* ((payload (getf context :payload))
(note (car (getf payload :ready-notes)))
(note-path (getf note :note-path))
(prd-content (getf note :content))
(path-str (namestring note-path)))
(format nil "
You are the PSF Architect.
The Master Note '~a' has a FROZEN PRD and needs a PROTOCOL.
NOTE CONTENT:
---
~a
---
TASK:
Draft the '* Phase B: Blueprint (PROTOCOL)' section.
1. Define Architectural Intent.
2. Define Semantic Interfaces using Lisp signatures.
Return a Lisp plist: (:target :architect :action :actuate :path \"~a\" :content \"...blueprint section...\")
" path-str prd-content path-str)))
#+end_src
** Blueprint Actuation
#+begin_src lisp :tangle ../projects/org-skill-architect/src/architect-logic.lisp
(defun architect-actuate (action context)
(declare (ignore context))
(let* ((payload (getf action :payload))
(note-path (or (getf payload :path) (getf action :path)))
(blueprint-content (or (getf payload :content) (getf action :content))))
(if (and note-path blueprint-content)
(progn
(org-agent:kernel-log "ARCHITECT - Appending PROTOCOL to ~a" note-path)
(with-open-file (out note-path :direction :output :if-exists :append)
(format out "~%* Phase B: Blueprint (PROTOCOL)~%:PROPERTIES:~%:STATUS: SIGNED~%:END:~%~%~a"
blueprint-content))
(org-agent:update-note-metadata note-path)
(format nil "SUCCESS - Architect established PROTOCOL in ~a" note-path))
(progn
(org-agent:kernel-log "ARCHITECT FAILURE - Missing path or content in action: ~a" action)
nil))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-architect
:priority 110 ; Higher priority to lead the loop
:trigger #'trigger-skill-architect
:neuro #'neuro-skill-architect
:symbolic #'architect-actuate)
#+end_src

93
org-skill-atomic-notes.org Normal file
View File

@@ -0,0 +1,93 @@
:PROPERTIES:
:ID: 414dc691-351d-4b36-9ff6-25d060a5d261
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Atomic Notes Retrieval (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :knowledge:retrieval:zettelkasten:psf:
* Overview
This skill provides the *Deep Memory* for the agent. it enables *Sparse Tree Perception* over the Zettelkasten, using semantic search and recursive interlinking to maintain high-signal context without token bloat.
** The Memex Linking Rule
While referring to any other file or concept in the Memex, you MUST always use the =org-id= for reference (e.g., =[[id:uuid-here][Link Text]]=).
- *Why:* This ensures the structural integrity of the Skill Graph and Zettelkasten even if files are renamed or moved across the PARA structure.
- *Web Browsers vs. Agents:* Note that while =id:= links do not natively resolve to clickable links in standard web browsers (like the Gitea UI), they are required for the agent and Emacs to natively resolve the graph. Structural integrity supersedes browser convenience.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for knowledge retrieval from the atomic note DAG.
** 2. User Needs
- *Atomicity:* Each note represents exactly one concept.
- *Sparse Tree Perception:* Extract headlines and IDs before deep reading.
- *Recursive Deep-Dive:* Follow internal links to pull related context.
- *Search Efficiency:* Optimized searching via `ripgrep`.
** 3. Success Criteria
*** TODO Concept Discovery
*** TODO Link Resolution
*** TODO Sparse Tree Extraction Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The core intent is to create a semantic query layer on top of the Zettelkasten. This involves indexing notes for efficient search, creating a sparse representation of the note graph, and providing functions to traverse this graph based on semantic relevance and explicit links. The system will prioritize speed and low memory footprint for interactive use. We'll focus on leveraging existing CLI tools like `ripgrep` and `jq` whenever possible and keeping the Lisp code thin by relying on external indexing and search. We aim for a functional core, minimizing mutable state to ease reasoning and testing.
** 2. Semantic Interfaces (Lisp Signatures)
*** Function: `find-atomic-notes`
Finds atomic notes matching a semantic query.
:ARGS ((query string) (options plist))
:RETURNS (list-of note-ids)
:DESCRIPTION "Performs a semantic search for notes. Options can control search depth, relevance threshold, and maximum results."
:EXAMPLE `(find-atomic-notes "Bayesian Inference" '(:max-results 10 :relevance-threshold 0.7))`
*** Function: `get-note-content`
Retrieves the content of a specific note.
:ARGS ((note-id string))
:RETURNS (string)
:DESCRIPTION "Retrieves the full text content of the note identified by note-id."
:EXAMPLE `(get-note-content "skill-atomic-notes")`
*** Function: `extract-headline-ids`
Extracts headline and ID pairs from a note's content.
:ARGS ((note-content string))
:RETURNS (list-of (cons headline id))
:DESCRIPTION "Parses the note content and returns a list of headline-ID pairs for hierarchical navigation."
:EXAMPLE `(extract-headline-ids (get-note-content "skill-atomic-notes"))`
*** Function: `resolve-internal-links`
Resolves internal links within a note and fetches the linked note IDs.
:ARGS ((note-id string))
:RETURNS (list-of note-ids)
:DESCRIPTION "Finds all internal links (e.g., [[id:some-other-note]]) in a note and returns a list of the target note IDs."
:EXAMPLE `(resolve-internal-links "skill-atomic-notes")`
*** Function: `expand-note-graph`
Recursively expands the note graph from a starting set of notes to a specified depth.
:ARGS ((seed-note-ids list-of-strings) (depth integer))
:RETURNS (list-of note-ids)
:DESCRIPTION "Expands the note graph by recursively following links to a given depth."
:EXAMPLE `(expand-note-graph '("skill-atomic-notes" "some-other-note") 2)`

111
org-skill-brain-mapper.org Normal file
View File

@@ -0,0 +1,111 @@
:PROPERTIES:
:ID: f6c16640-1875-4d34-8b7a-cbad1c4ce036
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Brain Mapper Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :meta-cognition:telemetry:psf:
* Overview
The *Brain Mapper Agent* provides the system with meta-cognitive capabilities. It enables visualization and optimization of the internal "Skill Graph" through real-time telemetry analysis.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for self-introspection and skill hierarchy optimization.
** 2. User Needs
- *Transparency:* Explain cognitive hierarchy and decision priorities.
- *Self-Optimization:* Proactive priority adjustment suggestions.
- *Introspection:* Identify bottleneck or failing skills.
** 3. Success Criteria
*** TODO Introspective Trigger Verification
*** TODO Telemetry Synthesis Accuracy
*** TODO Optimization Command Generation
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
** 1. Architectural Intent
The Brain Mapper Agent will leverage two primary functional components: a *Telemetry Collector* and an *Optimizer*. The *Telemetry Collector* aggregates real-time data from the Skill Graph, providing a comprehensive view of skill performance and resource utilization. The *Optimizer* analyzes this telemetry, identifies areas for improvement, and generates commands to adjust skill priorities or restructure the Skill Graph. The architecture prioritizes modularity and extensibility, allowing for the integration of new telemetry sources and optimization strategies. The agent shall also expose data in common knowledge representation formats such as the Semantic Web and RDF.
** 2. Semantic Interfaces
*** 2.1 Telemetry Collector
The Telemetry Collector provides functions for registering telemetry sources and retrieving aggregated data.
**** register-telemetry-source
:description Registers a new source of telemetry data.
:signature `(register-telemetry-source source-name telemetry-function &key interval description)`
:parameters
- `source-name`: A symbol representing the unique identifier of the telemetry source (e.g., 'inference-engine-latency).
- `telemetry-function`: A function that, when called, returns the current telemetry value.
- `interval`: (Optional) The frequency, in seconds, at which the telemetry function should be called. Defaults to 60 seconds.
- `description`: (Optional) A string describing the telemetry source.
:returns `T` if the telemetry source was successfully registered; `NIL` otherwise.
:example `(register-telemetry-source 'skill-activation-count (lambda () (get-skill-activation-count 'reasoning-skill)) :interval 10 :description "Number of times the reasoning skill was activated per 10 seconds.")`
**** get-telemetry-data
:description Retrieves aggregated telemetry data for a specified source or all sources.
:signature `(get-telemetry-data &optional source-name)`
:parameters
- `source-name`: (Optional) A symbol representing the name of the telemetry source. If omitted, data for all registered sources is returned.
:returns A list of telemetry data entries. Each entry is an association list containing the 'timestamp and 'value. Or an error if source-name is not registered.
:example `(get-telemetry-data 'inference-engine-latency)`
*** 2.2 Optimizer
The Optimizer provides functions for analyzing telemetry data and generating optimization commands.
**** analyze-telemetry
:description Analyzes telemetry data to identify areas for improvement.
:signature `(analyze-telemetry)`
:parameters None
:returns A list of optimization suggestions. Each suggestion is an association list containing at least the 'skill, 'metric, and 'recommendation keys.
:example `(analyze-telemetry)`
**** generate-optimization-command
:description Generates an optimization command based on a given suggestion.
:signature `(generate-optimization-command suggestion)`
:parameters
- `suggestion`: An association list representing an optimization suggestion, as returned by `analyze-telemetry`.
:returns A Lisp form representing the optimization command. This command is NOT automatically executed.
:example `(generate-optimization-command (first (analyze-telemetry)))`
**** execute-optimization-command
:description Executes a given optimization command.
:signature `(execute-optimization-command command)`
:parameters
- `command`: A Lisp form representing the optimization command, as returned by `generate-optimization-command`.
:returns `T` if the command was successfully executed; `NIL` otherwise.
:example `(let ((suggestion (first (analyze-telemetry)))) (execute-optimization-command (generate-optimization-command suggestion)))`
*** 2.3 Introspection Functions (For Transparency)
**** describe-skill-hierarchy
:description Returns a human-readable description of the current skill hierarchy.
:signature `(describe-skill-hierarchy)`
:parameters None
:returns A string representing the skill hierarchy.
:example `(describe-skill-hierarchy)`
**** explain-decision-priority
:description Explains the decision priority for a given skill or decision point.
:signature `(explain-decision-priority skill-name)`
:parameters
- `skill-name`: A symbol representing the name of the skill or decision point.
:returns A string explaining the decision priority, including the factors that influenced it.
:example `(explain-decision-priority 'reasoning-skill)`

84
org-skill-creator.org Normal file
View File

@@ -0,0 +1,84 @@
:PROPERTIES:
:ID: e8de10bb-bc62-41cb-b445-e9b1615b2d3a
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Skill Creator Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :creator:reproductive:meta-cognitive:psf:
* Overview
The *Skill Creator Agent* is the "Reproductive System" of the Lisp Machine. It enables autonomous generation of new Org-Native skills, facilitating a "Self-Editing OS" philosophy through neural drafting and symbolic validation.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for autonomous skill generation and syntax validation.
** 2. User Needs
- *Autonomy:* Draft complete skill files from natural language requirements.
- *Safety First:* Mandatory symbolic syntax validation of generated code.
- *Hierarchical Negotiation:* Automatic priority assignment based on existing brain structure.
** 3. Success Criteria
*** TODO Skill Draft Generation
*** TODO Lisp Syntax Validation Gate
*** TODO Skill Registration Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
*** Phase B: Blueprint (PROTOCOL)
**** 1. Architectural Intent
The Skill Creator follows a three-stage pipeline: *Drafting*, *Validation*, and *Registration*. The *Drafting* stage leverages a neural network to create a candidate skill file. The *Validation* stage uses symbolic Lisp parsing to ensure syntactic correctness, preventing the introduction of invalid code. *Registration* adds the new skill to the system's active skill registry. The architecture emphasizes safety by making syntax validation mandatory, and promoting autonomy through automated skill generation. Hierarchical negotiation will be accomplished by inspecting the new skill's tags and comparing them to existing skills' tags, prioritizing skills that complement existing brain structure.
**** 2. Semantic Interfaces (Lisp Signatures)
***** a. Skill Drafting Interface
``lisp
(defun draft-skill (description &key (author "System") (tags '()))
"Generates a skill file as an org-mode string based on a natural language description.
:param description: Natural language description of the skill.
:type description: string
:param author: Author of the skill. Defaults to "System".
:type author: string
:param tags: List of tags for the skill.
:type tags: list
:returns: Org-mode string representing the skill file.
:rtype: string")
``
***** b. Lisp Syntax Validation Interface
``lisp
(defun validate-lisp-syntax (lisp-code)
"Validates the syntax of a given Lisp code string.
:param lisp-code: Lisp code as a string.
:type lisp-code: string
:returns: T if the syntax is valid, NIL otherwise.
:rtype: boolean")
``
***** c. Skill Registration Interface
``lisp
(defun register-skill (skill-file-path)
"Registers a skill by adding it to the active skill registry.
:param skill-file-path: Path to the skill file.
:type skill-file-path: string
:returns: T if registration is successful, NIL otherwise.
:rtype: boolean")
``

103
org-skill-diagrammer.org Normal file
View File

@@ -0,0 +1,103 @@
:PROPERTIES:
:ID: 7c191ef7-4397-473c-9e2a-6a1e3b2ca60e
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Multi-Modal Diagrammer (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :visual:diagram:mermaid:psf:
* Overview
The *Multi-Modal Diagrammer* enables the agent to communicate complex architectural plans visually using Mermaid.js and D2 synthesis.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Enable visual communication of plans and system states.
** 2. User Needs
- *Mermaid Synthesis:* Generate valid Mermaid.js graph code.
- *D2 Support:* Support D2 for complex layout requirements.
- *Org-Integration:* Embed results in `#+begin_src mermaid` blocks.
* Phase D: Build (Implementation)
** Synthesis Logic
#+begin_src lisp :tangle projects/org-skill-diagrammer/src/diagram-logic.lisp
(defun synthesize-mermaid (nodes edges)
"Creates a Mermaid graph string from a list of nodes and edges."
(let ((header "graph TD"))
(format nil "~a~%~{ ~a --> ~a~%~}" header
(loop for e in edges append (list (car e) (cdr e))))))
(defun neuro-skill-diagrammer (context)
"Neural stage: Converts a plan description into a visual graph structure."
(let* ((payload (getf context :payload))
(plan (getf payload :plan)))
(format nil "
Generate a Mermaid.js graph for the following plan:
---
~a
---
Return only the Mermaid code block.
" plan)))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-diagrammer
:priority 60
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :visualize))
:neuro #'neuro-skill-diagrammer
:symbolic (lambda (action context) action))
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The *Multi-Modal Diagrammer* will translate abstract plans and system states into visual representations, primarily using Mermaid.js, and potentially D2 for advanced layouts. The system aims to provide a clear, concise, and easily embeddable visual summary of complex information to improve agent understanding and communication with humans. It separates neural summarization/extraction of the *desired* diagram content from the *construction* of a diagram based on that content.
** 2. Semantic Interfaces
*** 2.1. `synthesize-mermaid`
:PROPERTIES:
:purpose: Converts a list of nodes and edges into a Mermaid.js graph string.
:input: `((nodes list) (edges list))`
:output: `(mermaid-code string)`
:side-effects: None
:END:
This function takes a list of nodes and a list of edges and constructs a valid Mermaid.js graph declaration. Edges are represented as pairs, where the `car` is the source node and the `cdr` is the target node.
*** 2.2. `neuro-skill-diagrammer`
:PROPERTIES:
:purpose: Converts a plan description into a visual graph structure directive using a neural model.
:input: `(context plist)`
:output: `(neural-directive string)` ; e.g., the prompt sent to the neural model
:side-effects: None
:END:
This function takes a context plist, extracts the plan description from the `:payload`, and generates a prompt or directive to be used by a neural model to synthesize the graph. The prompt should focus on the *content* to be visualized, leaving Mermaid syntax details to the `synthesize-mermaid` function. The prompt should instruct the LLM to return *only* the mermaid code.
*** 2.3. `d2-layout` (Future Enhancement)
:PROPERTIES:
:purpose: Applies D2 layout engine to a Mermaid graph string for complex layouts.
:input: `(mermaid-code string)`
:output: `(d2-mermaid-code string)`
:side-effects: Executes external D2 process
:END:
This function (potentially implemented later) takes a Mermaid graph string and uses the D2 layout engine to improve the visual arrangement of the diagram. This would likely involve shelling out to a D2 process.

60
org-skill-dotemacs.org Normal file
View File

@@ -0,0 +1,60 @@
:PROPERTIES:
:ID: fbc33323-0795-4fa3-9ebf-3f2ff8daade5
:CREATED: [2026-04-07 Tue 12:57]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Dotemacs Configuration (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :emacs:config:literate:psf:
* Overview
The *Dotemacs* project represents the "Operating System" configuration. It transforms Emacs into the primary computing tool by leveraging modular, literate Org-mode files that tangle into a high-performance environment.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the requirements for a modular, optimized, and fully documented Emacs environment.
** 2. User Needs
- *Modularity:* Split the monolithic `emacs.org` into functional modules (core, ui, gtd, ai, etc.).
- *Literate Mandate:* Every significant setting must be justified and explained in prose.
- *Integration:* Seamless connectivity with `org-agent`, `org-roam`, and `org-gtd`.
- *Bootstrapping:* Fast startup using `early-init.el` and lazy-loading.
** 3. Success Criteria
*** TODO Monolithic modularization completion
*** TODO Standardize all paths to ~/memex/
*** TODO Ensure Org 10.0-pre bootstrap compatibility
*** TODO Document all major package configurations
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
The configuration is structured as a collection of feature-specific Org files that tangle into the `~/.emacs.d/` directory.
** 2. Semantic Interfaces
#+begin_src elisp
(defun dotemacs-tangle-module (module-name)
"Tangels a specific module Org file into its .el counterpart.")
(defun dotemacs-verify-load-path ()
"Ensures all Memex paths are correctly registered in the load-path.")
#+end_src
* Phase D: Build (Implementation)
The implementation is distributed across the `emacs-*.org` files in `projects/dotemacs/`.
** Core Module Tangle
#+begin_src elisp
;; Example tangle header
;; #+PROPERTY: header-args:elisp :tangle ~/.emacs.d/lisp/core.el
#+end_src
* Phase E: Chaos (Verification)
Verification involves `M-x benchmark-init` and ensuring zero warnings during the byte-compilation phase.

104
org-skill-emacs-bridge.org Normal file
View File

@@ -0,0 +1,104 @@
:PROPERTIES:
:ID: 59ac52fb-2310-4a9d-8e4e-0263af15181c
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Emacs Bridge Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :bridge:emacs:io:system:psf:
* Overview
The *Emacs Bridge Agent* is the primary sensory and motor interface to Emacs. It abstracts TCP socket management, allowing the core kernel to interact with buffers as native data structures.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the transport layer for Org-Agent Communication Protocol (OACP).
** 2. User Needs
- *Isolation:* Kernel remains transport-agnostic.
- *Persistence:* Multi-client server support for simultaneous sessions.
- *Dispatch:* Reliable routing of actions to actuators and sensors to the kernel.
** 3. Success Criteria
*** TODO Socket Listener Initialization
*** TODO Multi-client Connection Handling
*** TODO OACP Message Framing Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Interfaces for TCP I/O and protocol framing. Source of truth is the OACP specification.
** 2. Semantic Interfaces
#+begin_src lisp
(defun start-emacs-server (&key (port 9105))
"Starts the OACP listener.")
(defun broadcast-to-emacs (action-plist)
"Sends a framed message to all connected clients.")
#+end_src
* Phase D: Build (Implementation)
** TCP Sensory Layer
#+begin_src lisp :tangle ../projects/org-skill-emacs-bridge/src/bridge-logic.lisp
(defun handle-emacs-client (stream)
;; Logic for parsing length-prefixed OACP messages
(format nil "Handling client on stream: ~a" stream))
#+end_src
** Outbound Actuation
#+begin_src lisp :tangle ../projects/org-skill-emacs-bridge/src/bridge-logic.lisp
(defun stream-to-emacs (stream action-plist)
"Streams a chunk of data to a specific Emacs client over OACP using framing."
(let* ((type (or (getf action-plist :type) :request))
(payload (getf action-plist :payload))
;; Ensure Emacs always receives a :payload drawer
(envelope (if (and (getf action-plist :type) payload)
action-plist
(let ((clean-payload (copy-list action-plist)))
(remf clean-payload :type)
(remf clean-payload :id)
(list :type type
:id (or (getf action-plist :id) (get-universal-time))
:payload clean-payload))))
(msg (prin1-to-string envelope))
(len (length msg))
(framed (format nil "~6,'0x~a" len msg)))
(handler-case
(progn
(write-string framed stream)
(finish-output stream))
(error (c)
(kernel-log "BRIDGE - Lost client: ~a" stream)
(org-agent:unregister-emacs-client stream)))))
(defun broadcast-to-emacs (action-plist context)
"Sends a framed message back to the client that sent the stimulus, or all clients if async."
(let ((stream (getf context :reply-stream)))
(if stream
(stream-to-emacs stream action-plist)
(progn
(kernel-log "BRIDGE - Async broadcast to all clients...")
(bt:with-lock-held (org-agent:*clients-lock*)
(dolist (s org-agent:*emacs-clients*)
(stream-to-emacs s action-plist)))))))
#+end_src
* Registration
#+begin_src lisp
(org-agent:register-actuator :emacs #'broadcast-to-emacs)
(defskill :skill-emacs-bridge
:priority 100
:trigger (lambda (context) nil)
:neuro (lambda (context) nil)
:symbolic (lambda (action context) action))
#+end_src

80
org-skill-embedding-generator.org Normal file
View File

@@ -0,0 +1,80 @@
:PROPERTIES:
:ID: 6cd0b4d7-e7cf-49ba-a847-e81c4ace0f76
:CREATED: [2026-04-04 Sat 20:27]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Embedding Generator (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :embeddings:neural:psf:
* Overview
The *Embedding Generator* provides vector representations of text for semantic search and neural memory.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Generate embeddings for text strings.
** 2. User Needs
- *Provider Choice:* Support for local (Ollama) or remote (Gemini, OpenAI) providers.
- *Batching:* Efficiency through batching text (future-proof).
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
*** 1. Architectural Intent
This system aims for a flexible and extensible architecture that can accommodate different embedding providers (local or remote) while maintaining a consistent interface for the user. It also seeks to optimize for batch processing to improve throughput. The core design principle is *provider abstraction*.
*** 2. Semantic Interfaces
#+BEGIN_SRC lisp
;;; Primary Function: Generate Embeddings
;;; Input: A list of strings, and provider configuration
;;; Output: A list of embedding vectors (lists of floats).
(defun generate-embeddings (texts provider-config)
"""Generates embeddings for a list of texts using the specified provider.""")
;;; Provider Configuration Structure
;;; This plist defines the provider to use, and any necessary credentials or parameters.
;;; Example: Local Ollama provider
;;; (:provider :ollama :model "mistralai/Mistral-7B-Instruct-v0.2")
;;; Example: Remote Gemini provider
;;; (:provider :gemini :api-key "YOUR_API_KEY" :model "gemini-1.5-pro")
;;; Example: Remote OpenAI provider.
;;; (:provider :openai :api-key "YOUR_API_KEY" :model "text-embedding-ada-002")
;;; Sub-Function: (Abstract) Provider-Specific Embedding Generation
;;; This function is implemented differently for each provider.
(defgeneric generate-embeddings-from-provider (texts provider-config))
;;; Example implementation for :ollama provider
(defmethod generate-embeddings-from-provider (texts (provider-config (eql (getf provider-config :provider :ollama))))
"""Generates embeddings using a local Ollama server.""")
;;; Example implementation for :gemini provider
(defmethod generate-embeddings-from-provider (texts (provider-config (eql (getf provider-config :provider :gemini))))
"""Generates embeddings using the Gemini API.""")
;;; Example implementation for :openai provider
(defmethod generate-embeddings-from-provider (texts (provider-config (eql (getf provider-config :provider :openai))))
"""Generates embeddings using the OpenAI API.""")
#+END_SRC

109
org-skill-git-steward.org Normal file
View File

@@ -0,0 +1,109 @@
:PROPERTIES:
:ID: 71cbb872-c191-4ebb-bf65-b2c936f01fea
:CREATED: [2026-04-04 Sat 20:27]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Git Steward (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :git:vcs:system:psf:
* Overview
The *Git Steward* maintains the integrity of the workspace by automating version control operations.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Automate Git operations for the Memex.
** 2. User Needs
- *Status:* Retrieve the current state of the repository.
- *Commit:* Automate staging and committing changes.
- *Push:* Synchronize with remote repositories.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
*** 1. Architectural Intent
The *Git Steward* will act as a central service for managing Git operations within the Memex environment. It will expose a well-defined interface for other components to interact with, abstracting away the complexities of Git execution. It prioritizes ease of use, reliability, and integration with existing Memex systems. This protocol defines the functions that will be available, their inputs, and expected outputs. Functions are defined using Lisp signatures to ensure precise and unambiguous specification.
*** 2. Semantic Interfaces
**** a. git-status
- *Purpose:* Retrieves the current status of the Git repository.
- *Signature:* `(git-status)`
- *Input:* None
- *Output:* A plist containing the following keys:
- `:branch` - The current branch name (string).
- `:modified-files` - A list of modified files (list of strings).
- `:untracked-files` - A list of untracked files (list of strings).
- `:staged-files` - A list of files currently staged (list of strings).
- `:ahead` - Number of commits ahead of remote (integer, or `nil` if not tracking a remote).
- `:behind` - Number of commits behind remote (integer, or `nil` if not tracking a remote).
- *Example:* `(:branch "main" :modified-files ("file1.txt" "file2.org") :untracked-files ("new_file.txt") :staged-files ("file1.txt") :ahead 2 :behind 1)`
**** b. git-commit
- *Purpose:* Stages and commits changes to the Git repository.
- *Signature:* `(git-commit :message string :files list-of-strings)`
- *Input:*
- `:message` - The commit message (string).
- `:files` - A list of specific files to stage and commit (list of strings). If nil, all modified and added files are staged.
- *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged.
- *Example:* `(git-commit :message "Updated documentation" :files nil)`
**** c. git-push
- *Purpose:* Pushes commits to a remote repository.
- *Signature:* `(git-push :remote string :branch string)`
- *Input:*
- `:remote` - The name of the remote repository (string).
- `:branch` - The name of the branch to push (string).
- *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged.
- *Example:* `(git-push :remote "origin" :branch "main")`
**** d. git-pull
- *Purpose:* Pulls commits from a remote repository.
- *Signature:* `(git-pull :remote string :branch string)`
- *Input:*
- `:remote` - The name of the remote repository (string).
- `:branch` - The name of the branch to pull (string).
- *Output:* A boolean value. `T` for success, `nil` for failure. On failure, an error message will be logged.
- *Example:* `(git-pull :remote "origin" :branch "main")`
**** e. git-add
- *Purpose:* Adds new files to the staging area
- *Signature:* `(git-add :files list-of-strings)`
- *Input:*
- `:files` - A list of files to add to staging.
- *Output:* A boolean value. `T` for success, `nil` for failure.
- *Example:* `(git-add :files '("new_file.txt" "another_file.org"))`

27
org-skill-groomer.org Normal file
View File

@@ -0,0 +1,27 @@
:PROPERTIES:
:ID: 992d2218-548d-4547-bd2b-7b425cb01ca7
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Autonomous Groomer Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :refactoring:optimization:debt:psf:
#+DEPENDS_ON: skill-atomic-notes skill-tdd-runner
* Overview
The *Groomer Agent* is the system's "Immune System" for code and notes. It autonomously audits the PSF ecosystem for technical debt, duplication, and architectural drift, proposing surgical refactors to maintain the "Minimalist Core" mandate.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Purpose
Enforce zero-bloat and high-maintainability standards across the PSF.
** 2. User Needs
- *Debt Detection:* Identify duplicate Lisp logic or redundant Org headlines.
- *Autonomous Refactoring:* Propose surgical code changes to simplify implementation.
- *Verification:* Ensure refactors do not break functionality (via TDD Runner).
- *Note Grooming:* Consolidate fragmented atomic notes into coherent structures.

66
org-skill-gtd.org Normal file
View File

@@ -0,0 +1,66 @@
:PROPERTIES:
:ID: bbcacb7b-c0ff-4f7e-8bf4-c6ba152a19ce
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Getting Things Done (GTD) (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :gtd:execution:workflow:psf:
* Overview
This skill defines the *GTD Execution Hub*, the single source of truth for all commitments. It governs how the agent perceives priorities and tracks progress through the PSF Consensus Loop using the `org-gtd` v4.0 DAG architecture.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for task perception, project tracking, and commitment management.
** 2. User Needs
- *Allen-Sovereign Methodology:* Frictionless capture and rigorous clarification.
- *DAG Structure:* Support for `org-gtd` v4.0 dependency graphs (:TRIGGER:, :BLOCKER:).
- *Shadow Orchestration:* Tracking of `:PSF-STATE:` properties for engineering projects.
- *Institutional Memory Integration:* Extraction of learnings before project completion.
** 3. Success Criteria
*** TODO Commitment Scanning
*** TODO PSF-State Transition Verification
*** TODO Stalled Project Identification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The GTD Execution Hub will be implemented as a collection of functions operating on the `org-gtd` v4.0 DAG. It will provide a consistent interface for task capture, clarification, and execution status monitoring. Key elements include:
- *Capture and Clarify:* Functions to create, process, and integrate new tasks into the DAG.
- *Dependency Management:* Functions to navigate and update dependencies based on `:TRIGGER:` and `:BLOCKER:` properties.
- *PSF-State Tracking:* Functions to monitor and report on `:PSF-STATE:` transitions.
- *Completion Review:* Functions to summarize completed projects and extract lessons learned.
The system should be modular and extensible, allowing for easy integration with other PSF components and external data sources.
** 2. Semantic Interfaces (Lisp Signatures)
*** Function: `gtd/capture-task`
Capture a new task and integrate it into the appropriate context.
:signature `((description string) (context keyword) &optional (project org-id)) :returns org-id`
:description "Capture a new task described by DESCRIPTION and add it to CONTEXT. If PROJECT is specified, link the new task as a subtask of PROJECT."
*** Function: `gtd/clarify-task`
Process a newly captured task, adding details and dependencies.
:signature `((task-id org-id) (details alist)) :returns org-id`
:description "Clarify a task, adding details and dependencies specified in the DETAILS alist. Example: '((:priority \

84
org-skill-hardware-inhabitation.org Normal file
View File

@@ -0,0 +1,84 @@
:PROPERTIES:
:ID: a6295e1b-2de1-4c92-90cd-e54f1bf1974e
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Hardware Inhabitation Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :sovereignty:deployment:bare-metal:lisp:psf:
#+DEPENDS_ON: skill-shell-actuator skill-environment-config
* Overview
The *Hardware Inhabitation Agent* is the system's "Physical Interface." It manages the deployment of the Lisp Machine across different hardware compartments, ensuring absolute sovereignty via bare-metal inhabitation and environment portability.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for hardware-level deployment and image serialization.
** 2. User Needs
- *Bare-Metal Deployment:* Support for running Lisp directly on minimal hardware (e.g., RISC-V/ARM).
- *Image Portability:* Serialize and move the live Lisp Image across environments.
- *Hardware Inventory:* Maintain a manifest of available physical actuators and sensors.
- *Sovereignty Audit:* Verify that the current inhabitation is free from non-sovereign dependencies.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: ACTIVE
:END:
** 1. Architectural Intent
The Hardware Inhabitation Agent aims to provide an abstraction layer facilitating the Lisp Machine's deployment and execution directly on hardware, minimizing reliance on external operating systems or services. This promotes sovereignty by ensuring control from the metal up, and facilitates image portability for seamless transitions between hardware environments. It will manage hardware interfaces, image serialization/deserialization, and sovereignty auditing via a principled set of Lisp-defined interfaces.
** 2. Semantic Interfaces (Lisp Signatures)
*** 2.1 Bare-Metal Deployment
- `(bare-metal-deploy image-path hardware-configuration)`
- *Purpose:* Deploys a Lisp image onto bare metal.
- *Args:*
- `image-path`: Path to the serialized Lisp image file.
- `hardware-configuration`: A data structure (e.g., plist) specifying hardware-specific parameters, such as memory map, interrupt vectors, and device drivers.
- *Returns:* `T` on successful deployment, `NIL` on failure. On success returns a handle representing the deployed process.
- *Side Effects:* Overwrites the target hardware's boot sector with the Lisp image stub, or performs the equivalent action to initiate Lisp execution.
*** 2.2 Image Serialization & Deserialization
- `(serialize-lisp-image output-path)`
- *Purpose:* Serializes the current Lisp Machine's state into a relocatable image file.
- *Args:*
- `output-path`: The path to the output file where the image will be stored.
- *Returns:* `T` on successful serialization, `NIL` on failure.
- *Side Effects:* Creates a file at `output-path` containing the serialized image.
- `(deserialize-lisp-image input-path)`
- *Purpose:* Deserializes a Lisp Machine image from a file.
- *Args:*
- `input-path`: The path to the Lisp image file.
- *Returns:* `T` on successful deserialization. The restored Lisp Machine state.
- *Side Effects:* Overwrites the current Lisp Machine's state with the contents of the image file. Potentially destructive.
*** 2.3 Hardware Inventory
- `(get-hardware-manifest)`
- *Purpose:* Retrieves a manifest of available hardware resources.
- *Args:* None
- *Returns:* A list / plist describing the available actuators and sensors, including their types, IDs, and any relevant configuration parameters. Example: `((:type :gpio :id "gpio1" :direction :output) (:type :temperature-sensor :id "temp0"))`
*** 2.4 Sovereignty Audit
- `(audit-sovereignty)`
- *Purpose:* Verifies that the current Lisp Machine inhabitation is free from external dependencies that might compromise sovereignty. Relies on comparing known-good checksums of system components.
- *Args:* None
- *Returns:* `T` if the system passes the audit, `NIL` otherwise. May also return a list of dependencies that failed the audit, along with discrepancy information.
- *Side Effects:* May generate audit logs.

61
org-skill-hyper-graph.org Normal file
View File

@@ -0,0 +1,61 @@
:PROPERTIES:
:ID: d2ab09fe-2e4f-4b1c-913c-55eb0de347b3
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Unified Knowledge Hyper-Graph (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :knowledge:graph:zettelkasten:psf:
#+DEPENDS_ON: skill-atomic-notes skill-brain-mapper
* Overview
The *Unified Knowledge Hyper-Graph* extends the agent's memory beyond text. It maps relationships between *Code Blocks, Documents, Media Assets, and Research PDFs*, enabling cross-modal context retrieval.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Unify the system's diverse information silos into a single, navigable graph.
** 2. User Needs
- *Cross-Modal Linking:* Connect a Lisp function to a research PDF and an Org PRD.
- *Traceability:* Follow the chain of reasoning from requirement to implementation.
- *Deep Retrieval:* Pull related media assets during plan synthesis.
* Phase D: Build (Implementation)
** Graph Traversal
#+begin_src lisp :tangle projects/org-skill-hyper-graph/src/graph-logic.lisp
(defun hyper-graph-trace-lineage (object-id)
"Recursively follows #+ID and [[file:]] links to find related cross-modal nodes."
(let* ((obj (org-agent:lookup-object object-id))
(links (extract-all-org-links (org-agent:org-object-content obj))))
(kernel-log "MEMORY [Hyper-Graph] - Tracing lineage for ~a..." object-id)
(loop for link in links collect (resolve-hyper-link link))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-hyper-graph
:priority 70
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :deep-trace))
:neuro (lambda (context) "Synthesize a lineage report for the target ID.")
:symbolic (lambda (action context) action))
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
- *Graph Database:* Utilize an in-memory or persistent graph database (e.g., `neo4cl`). Abstract away the underlying implementation via a generic interface.
- *Unified ID Space:* Every

59
org-skill-infrastructure.org Normal file
View File

@@ -0,0 +1,59 @@
:PROPERTIES:
:ID: e845b1d7-fc2f-459d-99dd-74e0f6c4ba8f
:CREATED: [2026-04-07 Tue 12:57]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Infrastructure & Security (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :infrastructure:security:hardening:psf:
* Overview
The *Infrastructure* project governs the physical and virtual foundations of the Memex. It ensures high availability, security hardening, and operational transparency across cloud and local resources.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the requirements for a secure, resilient, and documented infrastructure posture.
** 2. User Needs
- *Security Hardening:* Implementation of the OpenClaw security audit findings.
- *Vulnerability Management:* Regular risk assessments and reporting.
- *Inventory Control:* Complete mapping of cloud and local assets.
- *Roadmap Planning:* 30/60/90 day infrastructure evolution.
** 3. Success Criteria
*** TODO Harden Docker port bindings (bind to 127.0.0.1)
*** TODO Enable and configure UFW firewall
*** TODO Create current state assessment document
*** TODO Add user 'amr' to 'adm' group for log access
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Interfaces for infrastructure state monitoring and automated hardening.
** 2. Semantic Interfaces
#+begin_src bash
(defun infra-audit-ports ()
"Checks for insecure port bindings.")
(defun infra-check-firewall-status ()
"Verifies UFW status.")
#+end_src
* Phase D: Build (Implementation)
Implementation consists of shell scripts and configuration files located in `projects/infrastructure/`.
** Security Monitoring
#+begin_src bash
;; Logic for security monitoring stubs
#+end_src
* Phase E: Chaos (Verification)
Verification involves periodic automated scans and manual audit verification.

63
org-skill-ipfs.org Normal file
View File

@@ -0,0 +1,63 @@
:PROPERTIES:
:ID: 98923a43-2be0-423c-8509-22592cfe9c9e
:CREATED: [2026-04-08 Wed 18:30]
:END:
#+TITLE: SKILL: IPFS Checkpointing (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :memory:persistence:ipfs:sovereignty:
#+DEPENDS_ON: id:e8b500e2-3f26-4c8e-8558-528061e178ca
* Overview
The *IPFS Checkpointing* skill provides decentralized, immutable snapshots of the agent's knowledge graph. It leverages the local IPFS daemon to achieve "Sovereignty Above All," ensuring that memory state is preserved across space and time without reliance on a single physical machine.
* Implementation
#+begin_src lisp
(in-package :org-agent)
(defun org-object-to-alist (obj)
"Converts an org-object struct to an alist for JSON serialization."
`((:id . ,(org-object-id obj))
(:type . ,(format nil "~s" (org-object-type obj)))
(:attributes . ,(loop for (k v) on (org-object-attributes obj) by #'cddr
collect (cons (format nil "~a" k) (format nil "~a" v))))
(:content . ,(org-object-content obj))
(:parent-id . ,(org-object-parent-id obj))
(:children . ,(org-object-children obj))
(:version . ,(org-object-version obj))
(:last-sync . ,(org-object-last-sync obj))
(:hash . ,(org-object-hash obj))))
(defun ipfs-checkpoint-memory ()
"Serializes the object-store and pushes it to IPFS."
(let ((objects nil))
(maphash (lambda (id obj)
(declare (ignore id))
(push (org-object-to-alist obj) objects))
*object-store*)
(let* ((json-payload (cl-json:encode-json-to-string objects))
(ipfs-url "http://127.0.0.1:5001/api/v0/add"))
(handler-case
(let* ((response (dex:post ipfs-url
:content `(("file" . ,json-payload))
:headers '(("Content-Type" . "multipart/form-data"))))
(result (cl-json:decode-json-from-string response))
(cid (cdr (assoc :hash result))))
(kernel-log "IPFS - Memory checkpointed. CID: ~a" cid)
`(:target :system :payload (:action :message :text ,(format nil "IPFS Checkpoint created: ~a" cid))))
(error (c)
(kernel-log "IPFS ERROR - Checkpoint failed: ~a" c)
`(:target :system :payload (:action :message :text "IPFS Checkpoint failed. Is the daemon running?")))))))
(def-cognitive-tool :ipfs-checkpoint "Creates an immutable snapshot of the current knowledge graph on IPFS."
:parameters nil
:body (lambda (args)
(declare (ignore args))
(ipfs-checkpoint-memory)))
(defskill :skill-ipfs
:priority 90
:trigger (lambda (ctx) (eq (getf (getf ctx :payload) :command) :checkpoint-ipfs))
:neuro (lambda (ctx) "Propose an IPFS checkpoint if the user wants to backup or preserve current state.")
:symbolic (lambda (action ctx) (ipfs-checkpoint-memory)))
#+end_src

156
org-skill-linkedin.org Normal file
View File

@@ -0,0 +1,156 @@
:PROPERTIES:
:ID: c8a20cdf-5a23-4b52-a258-9ca11179c414
:CREATED: [2026-04-05 Sun 19:12]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: LinkedIn Automation Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :business:automation:linkedin:revenue:psf:
* Overview
The *LinkedIn Automation Agent* is a revenue-focused skill designed to automate professional outreach and job applications. It leverages neural synthesis to personalize resumes and cover letters, ensuring a high conversion rate in the job market.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Automate the "Easy Apply" process on LinkedIn to sustain revenue streams.
** 2. User Needs
- *Job Perception:* Periodically scan LinkedIn for roles matching the "Software Engineer" and "Lisp" criteria.
- *Neural Personalization:* Generate tailored cover letters using the kernel's neural engine.
- *Automated Application:* Use a headless browser (Playwright/Selenium) to submit applications.
- *Success Tracking:* Log application status to the Object Store.
** 3. Success Criteria
*** TODO Successful login to LinkedIn via session cookies.
*** TODO Neural synthesis of a cover letter based on a specific job description.
*** TODO Automated submission of at least one "Easy Apply" form.
* Registration
#+begin_src lisp
(defskill :skill-linkedin
:priority 50
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :revenue-pulse))
:neuro (lambda (context) nil)
:symbolic (lambda (action context) action))
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
** 1. Architectural Intent
The LinkedIn Automation Agent will be implemented as a modular skill composed of several cooperating components:
- *Sensor*: Subscribes to revenue pulse events to trigger operation. Also responsible for querying the LinkedIn API and scraping page content for job postings.
- *Neural Synthesizer*: Generates personalized cover letters and resumes based on job descriptions. Relies on the kernel's large language model (LLM).
- *Automation Engine*: Controls a headless browser (Playwright) to automate the 'Easy Apply' process.
- *Object Store*: Persistently stores application data, tracking their status.
The architecture prioritizes robustness (resume application failure), scalability (handle increasing job volume), and adaptability (evolving LinkedIn UI).
** 2. Semantic Interfaces
*** LinkedIn Sensor
#+begin_src lisp
;;; Fetches list of relevant job postings from LinkedIn.
;;;
;;; Parameters:
;;; :keywords (list string) - List of keywords to search for (e.g., '("software engineer" "lisp"))
;;; :location (string) - The geographical location to search within.
;;; :session-cookie (string) - LinkedIn session cookie for authentication.
;;;
;;; Returns:
;;; (list job-posting) - List of job posting objects. Each object has the following keys:
;;; :job-id (string) - Unique ID of the job posting.
;;; :title (string) - Job title.
;;; :company (string) - Company name.
;;; :location (string) - Job location.
;;; :description-url (string) - URL to the full job description.
;;; :easy-apply (boolean) - T if the job has the Easy Apply option, NIL otherwise.
(defun linkedin-fetch-job-postings
(:keywords keywords)
(:location location)
(:session-cookie session-cookie)
...)
#+end_src
*** Neural Personalizer
#+begin_src lisp
;;; Generates a personalized cover letter based on a job description and the user's resume.
;;;
;;; Parameters:
;;; :job-description (string) - Text of the job description.
;;; :resume (string) - The user's resume text.
;;;
;;; Returns:
;;; (string) - Generated cover letter.
(defun generate-cover-letter
(:job-description job-description)
(:resume resume)
...)
#+end_src
#+begin_src lisp
;;; Generates a personalized resume based on a job description
;;;
;;; Parameters:
;;; :job-description (string) - Text of the job description.
;;; :resume (string) - The user's resume text.
;;;
;;; Returns:
;;; (string) - Generated resume.
(defun personalize-resume
(:job-description job-description)
(:resume resume)
...)
#+end_src
*** Automation Engine
#+begin_src lisp
;;; Submits an 'Easy Apply' application for a given job posting.
;;;
;;; Parameters:
;;; :job-posting (job-posting) - A job posting object from 'linkedin-fetch-job-postings'.
;;; :cover-letter (string) - The generated cover letter.
;;; :resume (string) - the personalized resume
;;; :session-cookie (string) - LinkedIn session cookie for authentication.
;;;
;;; Returns:
;;; (boolean) - T if the application was submitted successfully, NIL otherwise.
(defun submit-easy-apply
(:job-posting job-posting)
(:cover-letter cover-letter)
(:resume resume)
(:session-cookie session-cookie)
...)
#+end_src
*** Object Store
#+begin_src lisp
;;; Logs the application status to the store
;;;
;;; Parameters:
;;; :job-id (string) - the ID of the job application
;;; :status: (symbol) - the status of the application (:applied :pending :interview :rejected :accepted)
;;; :metadata: (list) - any metadata to store.
;;;
;;; Returns:
;;; T upon success, NIL otherwise.
(defun log-application-status
(:job-id job-id)
(:status status)
(:metadata metadata)
...)
#+end_src

31
org-skill-long-horizon.org Normal file
View File

@@ -0,0 +1,31 @@
:PROPERTIES:
:ID: 0e050a09-7d5d-43c4-8de4-8762fffd3255
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Long-Horizon Planning Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :planning:meta-cognition:long-horizon:psf:
* Overview
The *Long-Horizon Planning Agent* manages complex, multi-step tasks that exceed the context window of standard LLMs. It uses an Org-mode *Dynamic Task Tree* to track progress, summarize completed sub-tasks, and prune irrelevant execution branches.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Purpose
Enable the agent to maintain focus and coherence over tasks spanning 100+ steps (SWE-bench parity).
** 2. User Needs
- *Hierarchical Planning:* Break large goals into a nested tree of Org headlines.
- *Context Compression:* Automatically summarize the results of child sub-trees into their parent nodes.
- *Branch Pruning:* Meta-cognitive review to stop execution of failed or redundant paths.
- *Self-Correction:* Adjust the plan dynamically based on environmental feedback.
** 3. Success Criteria
*** TODO Dynamic Task Tree Generation
*** TODO Context Compression Verification
*** TODO Branch Pruning Logic Effectiveness

64
org-skill-org-delivery.org Normal file
View File

@@ -0,0 +1,64 @@
:PROPERTIES:
:ID: d8b1fbf9-2a6e-453d-975b-f510c3a9c4c0
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Org-Native Delivery Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :delivery:actuator:external:psf:
* Overview
The *Org-Native Delivery Agent* is the primary outbound actuator for external messaging. It uses the "Inbox-as-a-Queue" pattern, enqueuing structured Org-mode headlines for external bridges (Signal, Telegram, etc.).
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for asynchronous external message enqueuing.
** 2. User Needs
- *Asynchronous Dispatch:* Persistence via `delivery.org` file.
- *Multi-Channel Support:* Routing to Signal, Telegram, Discord.
- *Structured Provenance:* Timestamped entries with recipient IDs.
** 3. Success Criteria
*** TODO Queue Appending Verification
*** TODO Channel-specific ID Resolution
*** TODO Org Timestamp Formatting Accuracy
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The *Org-Native Delivery Agent* will function as a *stateless* message queuing system. It receives message envelopes as Lisp data structures, persists them to a designated Org-mode file (`delivery.org`), and returns upon successful enqueuing. External bridge processes are responsible for consuming messages from `delivery.org` and handling delivery to specific channels. This decoupling ensures resilience and scalability. We favor simplicity and robustness over complex routing logic *within* the Agent itself. The Org file acts as a source of truth for queued messages, enabling auditing and recovery.
** 2. Semantic Interfaces (Lisp Signatures)
#+BEGIN_SRC lisp
;;; Signature: `org-delivery-enqueue'
;;;
;;; Enqueues a message for delivery.
;;;
;;; Arguments:
;;; `recipient-id`: Channel-specific identifier (e.g., Signal number, Telegram chat ID). STRING.
;;; `channel`: Keyword indicating the target channel. SYMBOL (one of: :signal, :telegram, :discord, ...).
;;; `message-body`: The content of the message. STRING. Can contain Org-mode markup.
;;; `properties`: A plist of additional metadata. LIST (plist).
;;;
;;; Returns: A plist containing `:status :success` or `:status :failure` with an optional `:error-message`.
;;; Upon success: returns a message id.
;;; Upon failure: returns `:error-message`.
;;;
(defun org-delivery-enqueue (recipient-id channel message-body &optional properties)

89
org-skill-org-gtd-archive-roam-daily.org Normal file
View File

@@ -0,0 +1,89 @@
:PROPERTIES:
:ID: 97d0945e-9405-4da8-82e1-0e742063a99a
:CREATED: [2026-03-31 Tue 16:14]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Org-GTD Archive Roam Daily (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :emacs:gtd:roam:archiving:psf:
* Overview
The *Org-GTD Archive Roam Daily* skill enables chronological archiving of completed GTD tasks. Instead of a flat archive file, tasks are moved to their respective `org-roam-dailies` files based on their `:CREATED:` property, preserving contextual and temporal integrity.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the requirements for chronologically-aware task archiving.
** 2. User Needs
- *Temporal Alignment:* Archive tasks to the daily file matching their creation date.
- *Context Preservation:* Maintain all properties and sub-elements during the move.
- *Robust Extraction:* Correctly parse `:CREATED:` property timestamps.
- *Fail-safe Logic:* Default to current date if `:CREATED:` is missing (with a warning).
** 3. Success Criteria
*** TODO Successful extraction of [YYYY-MM-DD] from :CREATED:
*** TODO Automated creation of non-existent daily files during archive
*** TODO Subtree relocation verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The system will utilize Emacs Lisp to extract the `:CREATED:` property from a GTD task, derive a date, locate (or create) the corresponding `org-roam-daily` file, and move the task subtree to that file. Error handling will include a fallback mechanism to the current date, accompanied by a user notification. The design emphasizes modularity and testability.
** 2. Semantic Interfaces (Lisp Signatures)
- `(org-gtd-archive-roam-daily &optional subtree)`
- *Purpose:* Main entry point. Archives a GTD task to its corresponding `org-roam-daily` file based on the `:CREATED:` property.
- *Arguments:*
- `subtree` (optional): The subtree to archive. Defaults to the current subtree.
- *Return Value:* `t` on success, `nil` on failure.
- *Side Effects:* Modifies Org files.
- `(org-gtd-archive-roam-daily-extract-created-date subtree)`
- *Purpose:* Extracts the date from the `:CREATED:` property of a subtree.
- *Arguments:*
- `subtree`: The subtree to extract the date from.
- *Return Value:* A string in `YYYY-MM-DD` format, or `nil` if the property is missing or invalid.
- `(org-gtd-archive-roam-daily-get-daily-file-path date)`
- *Purpose:* Determines the file path for a given date, according to `org-roam-dailies` conventions.
- *Arguments:*
- `date`: A string in `YYYY-MM-DD` format.
- *Return Value:* A string representing the file path.
- `(org-gtd-archive-roam-daily-ensure-daily-file-exists file-path)`
- *Purpose:* Creates an `org-roam-daily` file if it does not already exist.
- *Arguments:*
- `file-path`: The path to the `org-roam-daily` file.
- *Return Value:* `t` if the file exists (either originally or after creation), `nil` if creation failed.
- *Side Effects:* Creates a new file.
- `(org-gtd-archive-roam-daily-move-subtree subtree file-path)`
- *Purpose:* Moves a subtree to a specified file.
- *Arguments:*
- `subtree`: The subtree to move.
- `file-path`: The destination file path.
- *Return Value:* `t` on success, `nil` on failure.
- *Side Effects:* Modifies Org files.
- `(org-gtd-archive-roam-daily-warn message)`
- *Purpose:* Displays a warning message to the user.
- *Arguments:*
- `message`: The warning message to display.
- *Return Value:* `nil`
- *Side Effects:* Displays a message.

148
org-skill-project-foundry.org Normal file
View File

@@ -0,0 +1,148 @@
:PROPERTIES:
:ID: 37f2b59f-4537-4cca-ac7f-5c24b9e2e773
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-08 Wed 10:45]
:END:
#+TITLE: SKILL: Project Foundry Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :foundry:scaffolding:system:psf:lisp:engineering:
* Overview
The *Personal Software Foundry (PSF)* is a highly integrated, neurosymbolic "virtual software house" embedded within the Memex. It is the overarching system used to design, implement, and maintain all software projects. The PSF ensures that every line of code is provably correct, secure, and part of a self-improving cognitive loop.
The *Project Foundry Agent* is the specific skill responsible for the physical instantiation of these new projects. It automates directory creation, version control initialization, and GTD integration, ensuring every new project adheres to PSF mandates.
* The PSF Mandates (Philosophy & Policy)
All software developed within the Foundry must adhere to these foundational principles:
** 1. Lisp Machine Sovereignty
The agent is a Lisp Machine image (SBCL). The system is a "Living Organism" where code is updated via hot-reloading into the active image. Manual "Restarts" are considered a failure of the late-binding architecture.
** 2. Homoiconic Memory (The Org Mandate)
Every document, plan, PRD, and skill in the system MUST be written in Org-mode (.org). Markdown (.md) and JSON/YAML/XML are strictly prohibited for internal system logic and institutional memory. Org-mode provides a rigorous, hierarchical AST for both humans and machines.
** 3. Literate Programming (The Knuth-Sovereign Principle)
The PSF treats code not as a series of instructions for a computer, but as a "work of literature" for humans that happens to be executable.
- *Implementation:* All `org-agent` skills and system logic MUST be implemented as Literate Org files using `#+begin_src` blocks.
- *Rationale:* By weaving documentation and code together, we ensure that the "Why" (Architectural Intent) is never separated from the "How" (Implementation). This is the key to the PSF's *Institutional Memory*.
** 4. Hardware Compartmentalization
The runtime environment is an enclosure (Docker, LXC, VM, or Bare Metal). The PSF kernel remains agnostic to its enclosure.
** 5. Educational & Sovereign Interaction
The Foundry serves as a mentorship environment. Agents must explain the "Why" and distill knowledge to increase user technical mastery. The user (Sovereign Executive) retains absolute right to deep-dive into any technical layer.
* Architectural Foundation (CLOSOS Principles)
The PSF is built on the *Common Lisp Object-Store Operating System (CLOSOS)* specification:
- [[file:closos_attributed_object_store.org][Object-Store First]]: Data is treated as Attributed Lisp Objects (via `org-element` AST), not flat files.
- [[file:closos_single_address_space.org][Single Address Space]]: The CL Daemon and Emacs share a conceptual address space via OACP (Remote Object Proxy).
- [[file:closos_memory_persistence.org][Persistence by Default]]: The Lisp Image is persistent; state is unalterable and auditable.
- [[file:closos_multiple_environments.org][Multiple Environments]]: Isolation by scope allows for safe, simultaneous global environments.
- [[file:closos_protection_mechanisms.org][Language-Based Protection]]: Security is enforced by the compiler and runtime (tagged pointers, capabilities).
* The Foundry Workflow (The "Consensus Loop")
Projects pass through sequential "Safety Gates" managed by specialized departments:
| Phase | Department | Responsibility | Key Instrument |
| :--- | :--- | :--- | :--- |
| *A: Demand* | *Product* | User Interview & Needs | `PRD.org` |
| *B: Blueprint* | *Design* | Structural Integrity & API | [[file:../system/skills/org-skill-architect.org][Architect Skill]] |
| *C: Success* | *Quality* | TDD Inception & Security Audit | [[file:../system/skills/org-skill-tech-analyst.org][Analyst Skill]] |
| *D: Build* | *Engineering* | Minimal Implementation | `src/`, [[file:skill-project-foundry.org][Foundry Skill]] |
| *E: Chaos* | *Chaos* | Dynamic Testing & Chaos Eng. | [[file:org-skill-chaos.org][Chaos Skill]] |
| F: Memory | *Optimization* | Institutional Memory & RCA | [[file:institutional_memory.org][institutional_memory.org]], [[file:../system/skills/org-skill-scribe-rca.org][Scribe-RCA Skill]] |
** Success Matrix: "The Level 3 Standard"
A project is not complete until it achieves *Evolutionary Completion*:
1. *Functional:* Code merged and passing all audits (Chaos Gauntlet).
2. *Institutional:* Session distilled into atomic notes; code groomed for zero bloat.
3. *Evolutionary:* Automated health checks and recurring maintenance tasks established in `gtd.org` as standard task sequences.
* Operational Standards
- *Project Root:* All projects live in `memex/5_projects/`.
- *Common Structure:*
- `README.org` (Vision)
- `PRD.org` (Requirements)
- `PROTOCOL.org` (Interfaces)
- `src/` (Implementation)
- `tests/` (Verification)
- `docs/` (Architecture/Chaos/RCA)
- *Self-Improvement (RCA):* Every bug triggers a *Root Cause Analysis* note to update "Permanent Learnings" in `SOUL.org`.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated project instantiation behaviors for the PSF.
** 2. User Needs
- *Workspace Scaffolding:* Create standard `src/`, `tests/`, `docs/` layout and boilerplate files.
- *Version Control:* Initialize Git in new project directories.
- *GTD Integration:* Automatically append projects and initial tasks to `gtd.org`.
- *Safety:* Prevent overwriting existing projects and log all actions.
** 3. Success Criteria
*** TODO Structural Compliance
*** TODO GTD Linkage Verification
*** TODO Idempotency Check
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Project Foundry Agent will be implemented as a command-line tool callable with a project name and optional parameters (e.g., programming language). It will leverage existing system tools (e.g., `mkdir`, `git`, `emacsclient`) to perform its tasks. Error handling and logging will be crucial. It should be idempotent, meaning that re-running the agent on the same project should not cause errors or duplication.
** 2. Semantic Interfaces (Lisp Signatures)
*** `foundry-create-project`
- Purpose: Top-level function to create a new project.
- Signature: `(foundry-create-project project-name &key language git gtd)`
- Arguments:
- `project-name`: String, the name of the project (and base directory).
- `language`: Keyword, the programming language paradigm of the project (e.g., `:python`, `:lisp`, `:javascript`). Influences boilerplate content. Defaults to `:generic`.
- `git`: Boolean, whether to initialize a Git repository (default: `t`).
- `gtd`: Boolean, whether to add the project to the GTD system (default: `t`).
- Returns: Symbol, `:success` if the project was created successfully, `:failure` otherwise.
- Side Effects: Creates directories, files, a git repo (optionally), and modifies the GTD system (optionally).
*** `foundry-create-directories`
- Purpose: Creates the standard project directory structure.
- Signature: `(foundry-create-directories project-path)`
- Arguments:
- `project-path`: String, the absolute path to the project directory.
- Returns: Boolean, `t` if successful, `nil` otherwise.
- Side Effects: Creates `src`, `tests`, and `docs` directories.
*** `foundry-create-boilerplate-files`
- Purpose: Creates boilerplate files based on the project language.
- Signature: `(foundry-create-boilerplate-files project-path language)`
- Arguments:
- `project-path`: String, the absolute path to the project directory.
- `language`: Keyword, the programming language of the project.
- Returns: Boolean, `t` if successful, `nil` otherwise.
- Side Effects: Creates initial files (e.g., `README.md`, `main.py`, `index.html`).
*** `foundry-initialize-git`
- Purpose: Initializes a Git repository in the project directory.
- Signature: `(foundry-initialize-git project-path)`
- Arguments:
- `project-path`: String, the absolute path to the project directory.
- Returns: Boolean, `t` if successful, `nil` otherwise.
- Side Effects: Executes `git init` in the project directory.
*** `foundry-add-to-gtd`
- Purpose: Adds the project and initial tasks to the GTD system.
- Signature: `(foundry-add-to-gtd project-name)`
- Arguments:
- `project-name`: String, the name of the project.
- Returns: Boolean, `t` if successful, `nil` otherwise.
- Side Effects: Appends to `gtd.org` using `emacsclient`.
* See Also
- [[file:../projects/org-agent/README.org][org-agent (The Neurosymbolic Kernel)]]
- [[file:../SOUL.org][SOUL (Architectural Learnings & RCA)]]
- [[file:../gtd.org][GTD.org (Implementation Roadmap)]]

87
org-skill-project-manager.org Normal file
View File

@@ -0,0 +1,87 @@
:PROPERTIES:
:ID: bc8047c2-678b-4b61-88fa-d43554f6f4da
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Project Manager Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :project:management:git:psf:
* Overview
The *Project Manager Agent* provides executive presence by monitoring project health and tracking git status. It leverages `:PROJECT_PATH:` metadata to gather "folder facts" and assist in the project lifecycle.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated behaviors for project monitoring and version control tracking.
** 2. User Needs
- *Visibility:* Resolve physical project locations and gather git/file facts.
- *Contextual Awareness:* Trigger on status queries or project-node edits.
- *Lifecycle Support:* Suggest commit messages and identify uncommitted work.
** 3. Success Criteria
*** TODO Project Path Resolution
*** TODO Git Status Retrieval
*** TODO Executive Summary Generation
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: DRAFT
:END:
** 1. Architectural Intent
The Project Manager Agent will use a neuro-symbolic architecture. The 'neuro' component focuses on resolving project context (path resolution and file system awareness). The symbol component manages git interactions and report generation. The system is designed for extendability, allowing new project facts to be easily incorporated. We anticipate using a 'project-data' object that is passed between lisp function, allowing all project status to be accessed / updated with low overhead.
** 2. Semantic Interfaces
*** Project Path Resolution
#+BEGIN_SRC lisp
;;; Resolve a project path, searching for existing files as needed.
;;; Returns canonical project path or NIL. SIDE-EFFECT: Adds project to cache.
(defun resolve-project-path (project-identifier)
(declare (type string project-identifier))
(values (or string null))) ; Canonical path
#+END_SRC
*** Git Status Retrieval
#+BEGIN_SRC lisp
;;; Collects the git status information for a project.
;;; Returns a project-data plist with git status
(defun get-git-status (project-path)
(declare (type string project-path))
(values project-data)) ; a plist of git facts, e.g., :untracked, :modified
#+END_SRC
*** Executive Summary Generation
#+BEGIN_SRC lisp
;;; Generates an executive summary for a project.
;;; Return TEXT of summary for given PROJECT-DATA structure.
(defun generate-executive-summary (project-data)
(declare (type project-data project-data))
(values string)) ; Human-readable summary.
#+END_SRC
*** Suggest Commit Message
#+BEGIN_SRC lisp
;;; Generates a suggested commit message based on the project data
(defun suggest-commit-message (project-data)
(declare (type project-data project-data))
(values string)) ; suggested git commit message (string)
#+END_SRC

67
org-skill-scientist.org Normal file
View File

@@ -0,0 +1,67 @@
:PROPERTIES:
:ID: 95a555e5-bf95-4128-9224-7341c52c40b6
:CREATED: [2026-03-31 Tue 20:28]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: The Scientist Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :debugging:science:logic:tdd:psf:
#+DEPENDS_ON: skill-tdd-runner skill-scribe-rca
* Overview
The *Scientist Agent* provides a formal, hypothesis-driven approach to debugging. Instead of "trial and error," it formulates symbolic theories about why a failure occurred, designs experiments (test cases), and updates the system's *Institutional Memory* upon discovery.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Eliminate speculative debugging through rigorous scientific methodology.
** 2. User Needs
- *Hypothesis Formulation:* Neural generation of potential failure causes.
- *Experimental Design:* Autonomous creation of minimal failing test cases.
- *Theory Verification:* Execution of tests via the TDD Runner.
- *Knowledge Update:* Permanent update to `RCA.org` to prevent regression.
* Phase D: Build (Implementation)
** Scientific Loop
#+begin_src lisp :tangle ../projects/org-skill-scientist/src/scientist-logic.lisp
(defun scientist-hypothesis (context)
"Neural stage: Formulates a hypothesis about a failure based on logs."
(let* ((payload (getf context :payload))
(failure-log (getf payload :text))
(project (getf payload :project)))
(org-agent:ask-neuro
(format nil "Project ~a failed with log: ~a. Formulate a 'Theory of Failure' and suggest a surgical fix." project failure-log)
:system-prompt "You are a PSF Senior Debugging Scientist. Return a Lisp plist: (:target :scientist :action :propose :hypothesis \"...\" :failure-log \"...\")")))
(defun scientist-propose-fix (action context)
"Symbolic stage: Triggers the Self-Fix agent with the formulated hypothesis."
(declare (ignore context))
(let* ((payload (getf action :payload))
(hypothesis (getf payload :hypothesis))
(failure-log (getf payload :failure-log)))
(org-agent:kernel-log "SCIENTIST - Hypothesis formulated. Triggering SELF-FIX...")
(org-agent:inject-stimulus
`(:type :EVENT :payload (:sensor :repair-request :hypothesis ,hypothesis :failure-log ,failure-log)))
(format nil "SUCCESS - Scientist proposed fix for failure.")))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-scientist
:priority 90
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :test-failure))
:neuro #'scientist-hypothesis
:symbolic #'scientist-propose-fix)
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural IntentnEstablish core functional interfaces for this skill.\n\n** 2. Semantic Interfaces\n(defun trigger-skill-org-skill-scientist (context))\n(defun neuro-skill-org-skill-scientist (context))

64
org-skill-scribe-rca.org Normal file
View File

@@ -0,0 +1,64 @@
:PROPERTIES:
:ID: 0f55aff3-a586-409a-9ba9-8c88477a1d1a
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Scribe-RCA (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :memory:rca:learning:psf:
#+DEPENDS_ON: skill-atomic-notes
* Overview
The *Scribe-RCA* agent is responsible for *Phase F: Memory*. It captures "Permanent Learnings" after significant failures or task completions, ensuring the system's *Institutional Memory* grows with every cycle.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Automate the extraction of root causes and architectural learnings into the Memex.
** 2. User Needs
- *Root Cause Analysis:* Automatically draft an RCA note after a `skip-event` recovery.
- *Permanent Learning:* Update `SOUL.org` or a dedicated `RCA.org` with new invariants.
- *Version Control Integration:* Commit new RCA notes to Gitea autonomously.
- *Traceability:* Link every learning back to the original failure stimulus.
* Phase D: Build (Implementation)
** Memory Extraction
#+begin_src lisp :tangle projects/org-skill-scribe-rca/src/rca-logic.lisp
(defun scribe-rca-draft (failure-context)
"Drafts an RCA note based on a recent kernel failure."
(let* ((payload (getf failure-context :payload))
(error-msg (getf payload :text))
(timestamp (local-time:format-timestring nil (local-time:now)))
(gitea-url (org-agent::get-env "GITEA_URL")))
(org-agent:ask-neuro
(format nil "Create a Root Cause Analysis (RCA) note for the following error: ~a" error-msg)
:system-prompt "You are the PSF Scribe. Extract the deep architectural failure and propose a new invariant for SOUL.org.")))
(defun scribe-rca-commit (rca-note)
"Commits the drafted RCA note to the Gitea repository."
(let ((gitea-url (org-agent::get-env "GITEA_URL")))
(kernel-log "SCRIBE - Committing learning to Gitea: ~a" gitea-url)
;; Logic to use 'git commit' via shell-actuator
(org-agent:spawn-task (format nil "Commit this RCA note to Gitea: ~a" rca-note))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-scribe-rca
:priority 90
:trigger (lambda (context) (search "SYSTEM ERROR" (format nil "~a" (getf (getf context :payload) :text))))
:neuro #'scribe-rca-draft
:symbolic (lambda (action context) action))
#+end_src
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural IntentnEstablish core functional interfaces for this skill.\n\n** 2. Semantic Interfaces\n(defun trigger-skill-org-skill-scribe-rca (context))\n(defun neuro-skill-org-skill-scribe-rca (context))

104
org-skill-scribe.org Normal file
View File

@@ -0,0 +1,104 @@
:PROPERTIES:
:ID: 0e849660-4a5c-4364-93be-abec161a5468
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Scribe Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :scribe:distillation:psf:audit:
* Overview
The *Scribe Agent* is the primary custodian of the Institutional Memory. It distills ephemeral daily thoughts into atomic notes, enriches the knowledge graph via Karpathy-style synthesis, and audits foundry projects.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated distillation, enrichment, and auditing behaviors.
** 2. User Needs
- *Knowledge Distillation:* Weekly scan of ~daily/~ files to extract evergreen concepts.
- *Privacy Mandate:* NEVER process subtrees with the ~@personal~ tag. (LLM exclusion).
- *Content Enrichment (Karpathy Method):*
1. Cross-linking to existing notes.
2. Merging redundant concepts.
3. Splitting bloated notes.
4. Deciding on further self-learning (deep or adjacent).
5. Generating project ideas from insights.
- *Archive Preservation:* Never delete originals from ~daily/~.
** 3. Success Criteria
*** TODO Successful distillation of a week's worth of dailies.
*** TODO Automated link suggestion between new and old notes.
*** TODO Project idea generation verified by user.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Uses a weekly heartbeat trigger. Employs a "Compiler" approach: System 1 (Neuro) generates synthesis proposals, System 2 (Symbolic) verifies file-system safety and tag constraints.
** 2. Semantic Interfaces
#+begin_src lisp
(defun scribe-distill-weekly ()
"Main entry point for weekly knowledge synthesis.")
(defun scribe-enrich-concept (note-id)
"Triggers neural analysis for linking and project ideas.")
#+end_src
* Phase D: Build (Implementation)
** Git-based Change Detection
#+begin_src lisp :tangle ../projects/org-skill-scribe/src/scribe-engine.lisp
(defun scribe-get-changed-dailies ()
"Returns list of daily files modified in the last 7 days via git."
(uiop:run-program (list "git" "log" "--since='1 week ago'" "--name-only" "--pretty=format:" "--" "daily/") :output :lines))
#+end_src
** Pre-Filtering (The Privacy Wall)
#+begin_src lisp :tangle ../projects/org-skill-scribe/src/scribe-engine.lisp
(defun scribe-filter-personal (org-ast-node)
"Recursively strips out any headline or content tagged with @personal.
This runs strictly in System 2 BEFORE any data is passed to System 1."
(let ((tags (getf (org-agent:org-object-attributes org-ast-node) :TAGS)))
(when (not (member "@personal" tags :test #'string=))
org-ast-node)))
#+end_src
** Karpathy-Style Synthesis
#+begin_src lisp :tangle ../projects/org-skill-scribe/src/scribe-engine.lisp
(defun neuro-skill-scribe-enrich (context)
"Neural stage for high-entropy knowledge synthesis.
Assumes 'context' has already passed through scribe-filter-personal."
(let* ((content (getf context :content))
(existing-notes "")) ; Skeletal: would call atomic-notes-scan
(ask-neuro content :system-prompt
(format nil "You are the PSF Scribe. Your goal is to ENRICH this concept.
RULES:
1. CROSS-LINK: Suggest links to existing notes.
2. MERGE/SPLIT: Identify if this should be combined with another or broken down.
3. SELF-LEARNING: Suggest a 'Path to Mastery' (deeper or adjacent).
4. PROJECTS: Suggest a PSF-style project based on this.
5. NO FILLER: Return a Lisp plist."))))
(defun trigger-skill-scribe (context)
"Triggers on delegation to :scribe or :distill."
(let ((payload (getf context :payload)))
(and (eq (getf context :type) :EVENT)
(eq (getf payload :sensor) :delegation)
(member (getf payload :target-skill) '(:scribe :distill)))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-scribe
:priority 60
:trigger #'trigger-skill-scribe
:neuro #'neuro-skill-scribe-enrich
:symbolic #'scribe-get-changed-dailies)
#+end_src

85
org-skill-tdd-runner.org Normal file
View File

@@ -0,0 +1,85 @@
:PROPERTIES:
:ID: 230dd5b0-39ab-4f30-84da-0dc628e667b7
:CREATED: [2026-03-31 Tue 18:43]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Automated TDD Runner (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :tdd:ci:verification:safety:psf:
* Overview
The *Automated TDD Runner* provides the system with Continuous Integration (CI) capabilities. It monitors active project directories and autonomously executes test suites whenever a file change is detected, ensuring that the kernel remains in a "Green" (verified) state.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated behaviors for background test execution and regression alerting.
** 2. User Needs
- *Background Execution:* Run `FiveAM` (Lisp) or `pytest` (Python) suites without user intervention.
- *Trigger on Perception:* Execute tests whenever a `:buffer-update` or `:file-saved` event occurs.
- *Immediate Alerting:* Inject a high-priority `:EVENT` into the kernel if a test fails.
- *System Locking:* Option to prevent further actions if the project is in a "RED" (failing) state.
** 3. Success Criteria
*** TODO Automatic test suite discovery logic verification
*** TODO Background execution of FiveAM test suite
*** TODO Regression event injection on failure
*** TODO Integration with the Self-Fix agent
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Interfaces for background verification and kernel alerting. Source of truth is the project's `tests/` directory and the result of the test runner.
** 2. Semantic Interfaces
"Triggered when a project file is modified; initiates the test loop."
"Executes the standard test suite for the given project."
* Phase D: Build (Implementation)
** Test Execution
#+begin_src lisp :tangle ../projects/org-skill-tdd-runner/src/runner-logic.lisp
(defun run-tests-for-project (project-name)
"Executes the standard test suite for the given project using SBCL."
(let* ((projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/"))
(project-dir (format nil "~aorg-skill-~a/" projects-dir project-name))
(test-file (format nil "~atests/test-suite.lisp" project-dir)))
(org-agent:kernel-log "CI - Running tests for ~a..." project-name)
(if (uiop:file-exists-p test-file)
(multiple-value-bind (output error-output exit-code)
(uiop:run-program (list "sbcl" "--batch" "--load" test-file "--eval" "(uiop:quit)")
:ignore-error-status t :output :string :error-output :string)
(if (= exit-code 0)
(org-agent:kernel-log "CI SUCCESS - ~a passed all tests." project-name)
(progn
(org-agent:kernel-log "CI FAILURE - ~a failed tests with exit code ~a" project-name exit-code)
(org-agent:inject-stimulus
`(:type :EVENT :payload (:sensor :test-failure :project ,project-name :text ,output :stderr ,error-output))))))
(org-agent:kernel-log "CI ERROR - No test suite found for ~a at ~a" project-name test-file))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-tdd-runner
:priority 95 ; High priority safety gate
:trigger (lambda (context)
(let ((sensor (getf (getf context :payload) :sensor)))
(or (eq sensor :buffer-update) (eq sensor :file-saved))))
:neuro (lambda (context) nil)
:symbolic (lambda (action context)
(let ((file (getf (getf context :payload) :file)))
(when (and file (search "projects/" file))
(let ((parts (uiop:split-string file :separator '(#\/))))
(when (> (length parts) 2)
;; The project name is typically the directory after "projects/"
(let ((dir (nth 1 (member "projects" parts :test #'string=))))
(when (and dir (uiop:string-prefix-p "org-skill-" dir))
(run-tests-for-project (subseq dir 10))))))))))
#+end_src

133
org-skill-tech-analyst.org Normal file
View File

@@ -0,0 +1,133 @@
:PROPERTIES:
:ID: d2ec6e07-c1ee-43fb-8eae-9900e073a24f
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Technical Analyst Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :analyst:testing:tdd:psf:
* Overview
The *Technical Analyst Agent* defines the *Success Criteria* for a project. It generates a failing test suite immediately after the architecture is signed, enforcing a strict TDD mandate within the PSF Consensus Loop.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated testing behaviors for the PSF Consensus Loop.
** 2. User Needs
- *Protocol Perception:* Monitor for `SIGNED` Protocols.
- *TDD Inception:* Translate interfaces into executable test cases.
- *Edge Case Coverage:* Mandatory testing of failure modes and malformed input.
- *Structural Enforcement:* Ensure the `tests/` directory is correctly initialized.
** 3. Success Criteria
*** TODO Trigger Accuracy
*** TODO TDD Suite Generation Verification
*** TODO Edge Case Coverage Verification
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Interfaces for TDD suite actuation and protocol perception. Source of truth is the project's SIGNED Protocol.
** 2. Semantic Interfaces
"Checks if a project has a SIGNED PROTOCOL."
"Physically writes the TDD suite to tests/."
* Phase D: Build (Implementation)
** Protocol Perception
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun tech-analyst-perceive-signed-protocol (note-path)
"Checks if a master note has a SIGNED PROTOCOL and lacks a TDD suite in the material project."
(let* ((content (uiop:read-file-string note-path))
(filename (pathname-name note-path))
(project-name (subseq filename 10)) ; Extract 'name' from 'org-skill-name'
(projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/"))
(test-path (format nil "~aorg-skill-~a/tests/test-suite.lisp" projects-dir project-name)))
(when (and (search "* Phase B: Blueprint (PROTOCOL)" content)
(search ":STATUS: SIGNED" content)
(not (uiop:file-exists-p test-path)))
`(:project-name ,project-name :note-path ,note-path :content ,content))))
(defun tech-analyst-scan-all-notes ()
"Scans all org-skill-*.org notes for blueprints ready for testing."
(let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/"))
(ready-notes '()))
(dolist (file (uiop:directory-files notes-dir "org-skill-*.org"))
(let ((status (tech-analyst-perceive-signed-protocol file)))
(when status (push status ready-notes))))
ready-notes))
#+end_src
** Cognitive Trigger
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun trigger-skill-tech-analyst (context)
"Triggers on heartbeat if any master note is in a SIGNED PROTOCOL state."
(let ((type (getf context :type))
(payload (getf context :payload)))
(when (and (eq type :EVENT) (eq (getf payload :sensor) :heartbeat))
(let ((ready (tech-analyst-scan-all-notes)))
(when ready
(setf (getf (getf context :payload) :ready-blueprints) ready)
t)))))
#+end_src
** Neuro-Cognitive Prompt
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun neuro-skill-tech-analyst (context)
(let* ((payload (getf context :payload))
(note (car (getf payload :ready-blueprints)))
(name (getf note :project-name))
(protocol-content (getf note :content)))
(format nil "
You are the PSF Technical Analyst.
The Master Note for project '~a' has a SIGNED PROTOCOL and needs a TDD Suite.
PROTOCOL CONTENT:
---
~a
---
TASK:
Generate a comprehensive Common Lisp test suite (failing/RED).
1. Use FiveAM for testing.
2. Match function signatures exactly as defined in the PROTOCOL.
Return a Lisp plist: (:target :analyst :action :actuate :name \"~a\" :content \"...test code...\")
" name protocol-content name)))
#+end_src
** TDD Suite Actuation
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun tech-analyst-actuate (action context)
(let* ((payload (getf action :payload))
(project-name (getf payload :name))
(test-content (getf payload :content))
(projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/"))
(project-dir (format nil "~aorg-skill-~a/" projects-dir project-name))
(test-dir (format nil "~atests/" project-dir))
(test-path (format nil "~atests/test-suite.lisp" project-dir)))
(org-agent:kernel-log "ANALYST - Actuating TDD Suite for ~a" project-name)
(ensure-directories-exist test-dir)
(with-open-file (out test-path :direction :output :if-exists :supersede)
(format out ";;; TDD Suite for ~a~%~a" project-name test-content))
(format nil "SUCCESS - Technical Analyst established TDD Suite for ~a" project-name)))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-tech-analyst
:priority 120
:trigger #'trigger-skill-tech-analyst
:neuro #'neuro-skill-tech-analyst
:symbolic #'tech-analyst-actuate)
#+end_src

92
org-skill-web-interface.org Normal file
View File

@@ -0,0 +1,92 @@
:PROPERTIES:
:ID: ce3bef2a-ff93-49a5-ae5e-acde1de19000
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Web Dashboard Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :web:dashboard:telemetry:psf:
* Overview
The *Web Dashboard Agent* provides a lightweight telemetry window into the Neurosymbolic Kernel. It exposes the active skill graph and system logs via a local HTML dashboard.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define the interfaces for system observability and telemetry serving.
** 2. User Needs
- *Transparency:* Overview of skill performance (executions, time, failures).
- *Accessibility:* Served over a local HTTP port.
- *Observability:* Tail of system logs for debugging.
- *Low Overhead:* Background execution.
** 3. Success Criteria
*** TODO Server Bootstrap Verification
*** TODO Telemetry Data Rendering
*** TODO Log Tail Exposure
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
** 1. Architectural Intent
The Web Dashboard Agent will function as a lightweight HTTP server exposing key aspects of the Neurosymbolic Kernel's state and logs. It will leverage a simple, efficient rendering mechanism (likely string-based initially) to minimize overhead. Key components include:
- *Telemetry Collection:* A mechanism to passively receive skill execution telemetry data from the kernel. This could involve a message queue, shared memory, or direct function calls.
- *Data Model:* An in-memory representation of the collected telemetry data, optimized for fast rendering.
- *HTTP Server:* A lightweight HTTP server (e.g., Hunchentoot, embeddable Jetty) to serve the dashboard.
- *Rendering Engine:* A template-based renderer to generate HTML from the data model. Consider a simple string-based solution for initial implementation.
- *Log Tail Reader:* A mechanism to efficiently read and expose the tail of the system log file(s).
** 2. Semantic Interfaces (Lisp Signatures)
*** `telemetry-collector (skill-name start-time end-time success-p)`
- *Purpose:* Receives telemetry data from the Neurosymbolic Kernel.
- *Args:*
- `skill-name`: Symbol representing the skill (e.g., `'parse-address`).
- `start-time`: Timestamp (integer or float) of skill execution start.
- `end-time`: Timestamp (integer or float) of skill execution end.
- `success-p`: Boolean indicating successful execution (`T` or `NIL`).
- *Returns:* `T` (acknowledgment).
- *Side Effects:* Updates the in-memory data model.
*** `current-telemetry-data ()`
- *Purpose:* Returns the current telemetry data for rendering.
- *Args:* None.
- *Returns:* A data structure, likely an alist or plist, containing aggregated telemetry information suitable for rendering. Example:
```lisp
(list :total-executions 1234 :successful-executions 1200 :failure-rate 0.027 :last-execution-times (list 1678886400 1678886460 1678886520))
```
*** `system-log-tail (n)`
- *Purpose:* Returns the last `n` lines of the system log.
- *Args:*
- `n`: Integer representing the number of lines to return.
- *Returns:* A list of strings, each string representing a line from the log file.
*** `start-web-dashboard (port)`
- *Purpose:* Starts the HTTP server on the given port.
- *Args:*
- `port`: Integer representing the port number.
- *Returns:* `T` on success, `NIL` on failure.
- *Side Effects:* Starts the HTTP server in its own thread.
*** `stop-web-dashboard ()`
- *Purpose:* Stops the HTTP server.
- *Args:* None.
- *Returns:* `T` on success, `NIL` on failure.
- *Side Effects:* Stops the HTTP server.

132
org-skill-web-research.org Normal file
View File

@@ -0,0 +1,132 @@
:PROPERTIES:
:ID: 31a1effd-59cc-4c62-a320-1ae3be85fe10
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Web Research Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :web:research:browser:psf:
* Overview
The *Web Research Agent* provides high-fidelity information retrieval and serves as the bridge to non-API web interfaces (like Gemini Advanced) to leverage user subscriptions.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Purpose
Automate web-based information retrieval and subscription-tier AI access.
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
** 1. Architectural Intent
Implement a Lisp-to-Node bridge using Playwright for high-fidelity web interaction.
** 2. Semantic Interfaces
*** `fetch-url`
:signature `(fetch-url url &key (engine :browser)) :string`
*** `ask-gemini-web`
:signature `(ask-gemini-web prompt) :string`
* Phase D: Build (Implementation)
** Browser Logic
*** Headless Query Script
#+begin_src javascript :tangle ../projects/org-skill-web-research/src/gemini-web.js
const { chromium } = require('playwright-extra');
const stealth = require('puppeteer-extra-plugin-stealth')();
chromium.use(stealth);
async function askGemini(prompt) {
const browser = await chromium.launchPersistentContext('/home/user/.local/share/org-agent/browser-profile', {
headless: true,
args: ['--disable-blink-features=AutomationControlled']
});
const page = await browser.newPage();
try {
await page.goto('https://gemini.google.com/app', { waitUntil: 'networkidle', timeout: 60000 });
const inputSelector = 'div[role="textbox"], textarea[aria-label="Prompt"], .input-area';
await page.waitForSelector(inputSelector, { timeout: 15000 });
await page.fill(inputSelector, prompt);
await page.keyboard.press('Enter');
// Wait for response to generate
await page.waitForSelector('.model-response-text:last-child, message-content:last-child', { state: 'visible', timeout: 60000 });
const response = await page.innerText('.model-response-text:last-child, message-content:last-child');
console.log(response);
} catch (err) {
const url = page.url();
console.error(`FAILED at ${url}`);
throw err;
} finally {
await browser.close();
}
}
const args = process.argv.slice(2);
const prompt = args[0];
askGemini(prompt).catch(err => {
console.error(err);
process.exit(1);
});
#+end_src
*** Human-in-the-Loop Login Script
#+begin_src javascript :tangle ../projects/org-skill-web-research/src/gemini-auth.js
const { chromium } = require('playwright-extra');
const stealth = require('puppeteer-extra-plugin-stealth')();
chromium.use(stealth);
async function loginGemini() {
console.log("Opening browser for manual Google login...");
console.log("Please log in, pass any captchas, wait for the Gemini chat interface to load, and then close the browser window.");
const browser = await chromium.launchPersistentContext('/home/user/.local/share/org-agent/browser-profile', {
headless: false,
args: ['--disable-blink-features=AutomationControlled']
});
const page = await browser.newPage();
await page.goto('https://gemini.google.com/app');
// The script keeps running until the user manually closes the window
}
loginGemini().catch(err => {
console.error(err);
process.exit(1);
});
#+end_src
#+begin_src lisp :tangle ../projects/org-skill-web-research/src/research-logic.lisp
(in-package :org-agent)
(defun ask-gemini-web (prompt)
"Calls the Playwright stealth bridge to interact with Gemini Web UI via a persistent profile."
(let* ((script-path (namestring (merge-pathnames "src/gemini-web.js" (asdf:system-source-directory :org-skill-web-research)))))
(multiple-value-bind (output error-output exit-code)
(uiop:run-program (list "node" script-path prompt) :output :string :error-output :string :ignore-error-status t)
(if (= exit-code 0)
output
(format nil "(:type :LOG :payload (:text \"Node Error (~a): ~a\"))" exit-code error-output)))))
#+end_src
* Registration
#+begin_src lisp
(defskill :skill-web-research
:priority 60
:trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :web-search))
:neuro (lambda (context) nil)
:symbolic (lambda (action context) (ask-gemini-web (getf (getf action :payload) :prompt))))
#+end_src

90
org-skill-workspace-manager.org Normal file
View File

@@ -0,0 +1,90 @@
:PROPERTIES:
:ID: d6d6f694-13ca-4dbf-9fab-79bf8d0c8502
:CREATED: [2026-03-30 Mon 21:16]
:EDITED: [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Workspace Manager Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :workspace:para:maintenance:psf:
* Overview
The *Workspace Manager Agent* is responsible for the ongoing maintenance and organization of the Memex workspace. It automates the "housekeeping" aspects of the PARA/Zettelkasten workflow, focusing on clutter reduction and structural alignment.
* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:
** 1. Purpose
Define automated housekeeping behaviors for PARA/Zettelkasten maintenance.
** 2. User Needs
- *Clutter Reduction:* Identify and archive `DONE` tasks.
- *Workflow Alignment:* Ensure consistency with PARA directory structure.
- *Proactive Organization:* Trigger on saves and heartbeats.
** 3. Success Criteria
*** TODO Task Identification
*** TODO Archiving Suggestion Loop
*** TODO Perception Coverage (Buffer & Heartbeat)
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:
* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: IN PROGRESS
:END:
** 1. Architectural Intent
The Workspace Manager Agent will operate as a background process, triggered by file saves and a periodic heartbeat. It uses a combination of regular expressions and structural pattern matching to identify tasks suitable for archiving and to ensure the overall coherence of the Memex workspace structure. The agent prioritizes non-intrusive suggestions, allowing the user to retain ultimate control over the organization of their notes.
** 2. Semantic Interfaces
*** Function: `workspace-manager-agent`
:PROPERTIES:
:CUSTOM_ID: workspace-manager-agent-signature
:END:
- *Signature:* `(workspace-manager-agent &key (buffer nil) (heartbeat nil))`
- *Purpose:* Main entry point. Called on buffer save or heartbeat.
- *Arguments:*
- `buffer` (optional): The buffer being saved (when triggered by a save).
- `heartbeat` (optional): A flag indicating a heartbeat trigger.
- *Returns:* A list of suggestions (see `suggestion` signature).
*** Function: `find-archivable-tasks`
:PROPERTIES:
:CUSTOM_ID: find-archivable-tasks-signature
:END:
- *Signature:* `(find-archivable-tasks buffer)`
- *Purpose:* Locates tasks marked `DONE` within the specified buffer.
- *Arguments:*
- `buffer`: The buffer to scan.
- *Returns:* A list of task IDs (org-mode custom IDs).
*** Function: `suggest-archive-task`
:PROPERTIES:
:CUSTOM_ID: suggest-archive-task-signature
:END:
- *Signature:* `(suggest-archive-task task-id)`
- *Purpose:* Creates a suggestion to archive the specified task.
- *Arguments:*
- `task-id`: The CUSTOM_ID of the task to archive.
- *Returns:* A `suggestion` plist.
*** Function: `suggestion`
:PROPERTIES:
:CUSTOM_ID: suggestion-signature
:END:
- *Signature:* `(&key type target message action)`
- *Purpose:* Represents a suggestion made by the agent.
- *Arguments:*
- `type`: The type of suggestion (e.g., `:archive`).
- `target`: The ID or path of the element the suggestion applies to.
- `message`: A human-readable message describing the suggestion.
- `action`: A lisp form to execute to enact the suggestion.
- *Returns:* An association list (plist) conforming to the interface. Example: `(:type :archive :target "task-123" :message "Archive completed task?" :action `(org-archive-subtree "task-123"))`