: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"))`