memex/notes/org-skill-architect.org

SKILL: Architect Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • PRD Perception
  • Note Scanning
  • Cognitive Trigger
  • Neuro-Cognitive Prompt
  • Blueprint Actuation
• Registration

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)

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)

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

(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))))

Note Scanning

(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))

Cognitive Trigger

(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)))))

Neuro-Cognitive Prompt

(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)))

Blueprint Actuation

(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))))

Registration

(defskill :skill-architect
  :priority 110 ; Higher priority to lead the loop
  :trigger #'trigger-skill-architect
  :neuro #'neuro-skill-architect
  :symbolic #'architect-actuate)