#+TITLE: SKILL: Architect Agent (Universal Literate Note)
#+ID: skill-architect
#+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 human requirements and machine code, ensuring structural integrity before implementation.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define automated architectural behaviors for the PSF Consensus Loop.

** 2. User Needs
- **PRD Perception:** Monitor for `FROZEN` PRDs.
- **Semantic Translation:** Translate ambiguous needs into Lisp-style interfaces.
- **Memory Integration:** Reference `institutional-memory.org` for design choices.
- **Physical Actuation:** Write the `PROTOCOL.org` to the project directory.

** 3. Success Criteria
*** TODO Trigger Accuracy
*** TODO Protocol Generation Verification
*** TODO File Integrity Check

* 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
#+begin_src lisp
(defun architect-perceive-frozen-prd (project-name)
  "Checks if a project has a FROZEN PRD.")

(defun architect-actuate (project-name blueprint-content)
  "Physically writes the PROTOCOL.org file.")
#+end_src

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

(defun architect-scan-all-notes ()
  "Scans all org-skill-*.org notes for demands ready for blueprinting."
  (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/"))
        (ready-notes '()))
    (dolist (file (uiop:directory-files notes-dir "org-skill-*.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)))
    (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...\")
    " note-path prd-content note-path)))
#+end_src

** Blueprint Actuation
#+begin_src lisp :tangle projects/org-skill-architect/src/architect-logic.lisp
(defun architect-actuate (action context)
  (let* ((payload (getf action :payload))
         (note-path (getf payload :path))
         (blueprint-content (getf payload :content)))
    
    (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))
    (format nil "SUCCESS - Architect established PROTOCOL in ~a" note-path)))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-architect
  :priority 70
  :trigger #'trigger-skill-architect
  :neuro #'neuro-skill-architect
  :symbolic #'architect-actuate)
#+end_src