memex/notes/org-skill-workspace-manager.org

SKILL: Workspace Manager Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Task Identification
    • Archiving Suggestion Loop
    • Perception Coverage (Buffer & Heartbeat)
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
    • Function: `workspace-manager-agent`
    • Function: `find-archivable-tasks`
    • Function: `suggest-archive-task`
    • Function: `suggestion`

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)

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)

Phase B: Blueprint (PROTOCOL)

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`

• 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`

• 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`

• 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`

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