memex/notes/org-skill-org-mode.org

SKILL: Org-Mode & AST Manipulation (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • ID Uniqueness Enforcement
    • Literate Block Parsing
    • Attachment Link Validation
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Node Parsing
  • Attachment Protocol
• Registration

Overview

This skill defines the Grammar of the Memex. It establishes the rules for treating plain text as a structured, hierarchical database. Org-mode is our *Homoiconic Memory*—documentation for humans and AST for the agent.

Phase A: Demand (PRD)

1. Purpose

Define the structural rules and manipulation interfaces for the Org-mode AST.

2. User Needs

• Everything is a Node: Mandatory headlines, properties, and unique IDs.
• Literate Programming: Code must be wrapped in narrative-rich blocks.
• Naming & Paths: Strict kebab-case and flat directory structure.
• Binary Integrity: Management of attachments via the Attachment Protocol.

3. Success Criteria

TODO ID Uniqueness Enforcement

TODO Literate Block Parsing

TODO Attachment Link Validation

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

Interfaces for perceiving and manipulating Org nodes. Source of truth is the filesystem and the Org element parser.

2. Semantic Interfaces

(defun org-mode-parse-node (id)
  "Retrieves the AST of a specific node by its ID.")

(defun org-mode-validate-structure (file-path)
  "Checks a file for compliance with the Org Mandate.")

Phase D: Build (Implementation)

Node Parsing

(defun org-mode-parse-node (id)
  "Retrieves the AST of a specific node by its ID."
  (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/")))
    (kernel-log "AST - Parsing node: ~a" id)
    ;; In practice, this uses cl-org-mode or similar element parsers
    (uiop:run-program (list "grep" "-r" (format nil ":ID: ~a" id) notes-dir) :output :string)))

Attachment Protocol

(defun org-mode-get-attachment-path (node-id filename)
  "Resolves the physical path of an attachment based on node ID."
  (format nil "attachments/~a/~a" node-id filename))

Registration

(defskill :skill-org-mode
  :priority 100
  :trigger (lambda (context) nil)
  :neuro (lambda (context) nil)
  :symbolic #'org-mode-parse-node)